From c3526d0529e3defc01a0b59ff4f44aba5e2d88eb Mon Sep 17 00:00:00 2001 From: foorack Date: Thu, 26 Aug 2021 12:56:53 +0200 Subject: [PATCH 1/6] feture: Initial documentation of Permissions API --- .spectral.yaml | 9 +- openapi/components/paths/permissions.yaml | 111 +++++++++++++++++++ openapi/components/schemas/Permission.yaml | 37 +++++++ openapi/components/schemas/PermissionID.yaml | 4 + openapi/openapi.yaml | 9 +- 5 files changed, 166 insertions(+), 4 deletions(-) create mode 100644 openapi/components/paths/permissions.yaml create mode 100644 openapi/components/schemas/Permission.yaml create mode 100644 openapi/components/schemas/PermissionID.yaml diff --git a/.spectral.yaml b/.spectral.yaml index 4322e3bb..44f66cf4 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -3,8 +3,11 @@ formats: extends: - 'spectral:oas' rules: - contact-properties: warn - info-license: warn - license-url: warn oas3-parameter-description: info tag-description: hint + + # Rules for sub schema + info-license: hint + license-url: hint + oas3-api-servers: hint + info-contact: hint \ No newline at end of file diff --git a/openapi/components/paths/permissions.yaml b/openapi/components/paths/permissions.yaml new file mode 100644 index 00000000..651605dc --- /dev/null +++ b/openapi/components/paths/permissions.yaml @@ -0,0 +1,111 @@ +openapi: 3.0.0 +info: + title: permissions + version: '1.0' + description: 'Permissions are a way to individually grant specific access to a user, often through a license such as VRC+ subscription.' +paths: + /auth/permissions: + get: + summary: Get Assigned Permission + operationId: getAssignedPermissions + responses: + '200': + $ref: '#/components/responses/PermissionListResponse' + '401': + $ref: ../responses/MissingCredentialsError.yaml + tags: + - permissions + description: Returns a list of all permissions currently granted by the user. Permissions are assigned e.g. by subscribing to VRC+. + parameters: [] + /permissions: + get: + summary: Get Permissions + tags: [] + responses: + '200': + $ref: '#/components/responses/PermissionListResponse' + '401': + $ref: ../responses/MissingCredentialsError.yaml + operationId: getPermissions + x-internal: true + description: '**REQUIRES INTERNAL ADMIN CREDENTIALS**. Returns a list of all existing permissions, just like `/users` with empty search would.' + '/permissions/{permissionId}': + parameters: + - $ref: '#/components/parameters/permissionId' + get: + summary: Get Permission + tags: [] + responses: + '200': + $ref: '#/components/responses/PermissionResponse' + '401': + $ref: ../responses/MissingCredentialsError.yaml + operationId: getPermission + description: 'Returns a single permission. This endpoint is pretty useless, as it returns the exact same information as `/auth/permissions`.' +tags: + $ref: ../../openapi.yaml#/tags +components: + responses: + PermissionListResponse: + description: Returns a list of Permission objects. + content: + application/json: + schema: + type: array + items: + $ref: ../schemas/Permission.yaml + examples: + Standard Permissions Inherited By VRC+: + value: + - id: prms_fe07c8a7-a4ca-4eda-97e5-e241040ef6f8 + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-trust-boost + - id: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-extra-favorites-avatar-groups + data: + maxFavoritesPerGroup: + avatar: 25 + maxFavoriteGroups: + avatar: 4 + - id: prms_ac88a3e0-c236-47c7-9b47-d795551b7520 + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-early-adopter-tags + data: + tags: + - system_early_adopter + - id: prms_76f33deb-dd5d-46b7-b79d-e1f8f0a9a1e0 + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-supporter-tags + data: + tags: + - system_supporter + - id: prms_0d9549db-d30a-48f3-a6b8-6741ce5a4283 + ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b + name: permission-invite-photos + data: {} + - id: prms_153ac0b7-c2dd-43f9-96e3-c61fd2e85509 + ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b + name: permission-profile-pic-override + data: {} + - id: prms_1d9549db-d30a-48f3-a6b8-6741ce5a4283 + ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b + name: permission-user-icons + data: {} + - id: prms_dc02c512-4c03-479c-8c6a-d9329c023baf + ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b + name: permission-user-gallery + data: {} + PermissionResponse: + description: Returns a single Permission object. + content: + application/json: + schema: + $ref: ../schemas/Permission.yaml + parameters: + permissionId: + name: permissionId + in: path + required: true + schema: + type: string diff --git a/openapi/components/schemas/Permission.yaml b/openapi/components/schemas/Permission.yaml new file mode 100644 index 00000000..243523e5 --- /dev/null +++ b/openapi/components/schemas/Permission.yaml @@ -0,0 +1,37 @@ +description: '' +type: object +x-examples: + example-1: + id: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-extra-favorites-avatar-groups + data: + maxFavoritesPerGroup: + avatar: 25 + maxFavoriteGroups: + avatar: 4 +properties: + id: + $ref: ./PermissionID.yaml + ownerId: + $ref: ./UserID.yaml + name: + type: string + minLength: 1 + example: permission-invite-photos + data: + type: object +required: + - id + - ownerId + - name +title: Permission +examples: + - id: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-extra-favorites-avatar-groups + data: + maxFavoritesPerGroup: + avatar: 25 + maxFavoriteGroups: + avatar: 4 diff --git a/openapi/components/schemas/PermissionID.yaml b/openapi/components/schemas/PermissionID.yaml new file mode 100644 index 00000000..cb872830 --- /dev/null +++ b/openapi/components/schemas/PermissionID.yaml @@ -0,0 +1,4 @@ +type: string +title: PermissionID +pattern: 'prms_[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}' +example: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 1e2a8eda..d53bc2fe 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -1933,7 +1933,7 @@ paths: '200': $ref: ./components/responses/PlayerModerationRemovedSuccess.yaml '401': - $ref: '#/components/responses/MissingCredentials' + $ref: ./components/responses/MissingCredentialsError.yaml '403': $ref: ./components/responses/PlayerModerationDeleteOthersError.yaml description: Deletes a specific player moderation based on it's `pmod_` ID. The website uses `unmoderateUser` instead. You can delete the same player moderation multiple times successfully. @@ -1945,6 +1945,12 @@ paths: name: playerModerationId in: path required: true + /auth/permissions: + $ref: ./components/paths/permissions.yaml#/paths/~1auth~1permissions + /permissions: + $ref: ./components/paths/permissions.yaml#/paths/~1permissions + '/permissions/{permissionId}': + $ref: ./components/paths/permissions.yaml#/paths/~1permissions~1{permissionId} components: schemas: {} securitySchemes: @@ -2664,6 +2670,7 @@ tags: - name: friends - name: notifications - name: playermoderation + - name: permissions - name: system - name: users - name: worlds From 0dda70799650cea3623aa65c52f75e2be50a6190 Mon Sep 17 00:00:00 2001 From: foorack Date: Thu, 26 Aug 2021 13:45:58 +0200 Subject: [PATCH 2/6] ci: Removed breaking example --- openapi/components/paths/permissions.yaml | 44 +---------------------- openapi/openapi.yaml | 2 +- 2 files changed, 2 insertions(+), 44 deletions(-) diff --git a/openapi/components/paths/permissions.yaml b/openapi/components/paths/permissions.yaml index 651605dc..2add6a98 100644 --- a/openapi/components/paths/permissions.yaml +++ b/openapi/components/paths/permissions.yaml @@ -1,4 +1,4 @@ -openapi: 3.0.0 +openapi: 3.0.3 info: title: permissions version: '1.0' @@ -54,48 +54,6 @@ components: type: array items: $ref: ../schemas/Permission.yaml - examples: - Standard Permissions Inherited By VRC+: - value: - - id: prms_fe07c8a7-a4ca-4eda-97e5-e241040ef6f8 - ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b - name: permission-trust-boost - - id: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff - ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b - name: permission-extra-favorites-avatar-groups - data: - maxFavoritesPerGroup: - avatar: 25 - maxFavoriteGroups: - avatar: 4 - - id: prms_ac88a3e0-c236-47c7-9b47-d795551b7520 - ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b - name: permission-early-adopter-tags - data: - tags: - - system_early_adopter - - id: prms_76f33deb-dd5d-46b7-b79d-e1f8f0a9a1e0 - ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b - name: permission-supporter-tags - data: - tags: - - system_supporter - - id: prms_0d9549db-d30a-48f3-a6b8-6741ce5a4283 - ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b - name: permission-invite-photos - data: {} - - id: prms_153ac0b7-c2dd-43f9-96e3-c61fd2e85509 - ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b - name: permission-profile-pic-override - data: {} - - id: prms_1d9549db-d30a-48f3-a6b8-6741ce5a4283 - ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b - name: permission-user-icons - data: {} - - id: prms_dc02c512-4c03-479c-8c6a-d9329c023baf - ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b - name: permission-user-gallery - data: {} PermissionResponse: description: Returns a single Permission object. content: diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index d53bc2fe..fa66a1bf 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -1,4 +1,4 @@ -openapi: 3.0.0 +openapi: 3.0.3 info: title: VRChat API Documentation version: 1.0.2 From fc5e4392644ab64ccfdcbd0b5626c5451be3a36e Mon Sep 17 00:00:00 2001 From: Foorack Date: Thu, 26 Aug 2021 13:55:50 +0200 Subject: [PATCH 3/6] Undo of 0dda70799650cea3623aa65c52f75e2be50a6190 --- openapi/components/paths/permissions.yaml | 42 +++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/openapi/components/paths/permissions.yaml b/openapi/components/paths/permissions.yaml index 2add6a98..4509d3ac 100644 --- a/openapi/components/paths/permissions.yaml +++ b/openapi/components/paths/permissions.yaml @@ -54,6 +54,48 @@ components: type: array items: $ref: ../schemas/Permission.yaml + examples: + Standard Permissions Inherited By VRC+: + value: + - id: prms_fe07c8a7-a4ca-4eda-97e5-e241040ef6f8 + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-trust-boost + - id: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-extra-favorites-avatar-groups + data: + maxFavoritesPerGroup: + avatar: 25 + maxFavoriteGroups: + avatar: 4 + - id: prms_ac88a3e0-c236-47c7-9b47-d795551b7520 + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-early-adopter-tags + data: + tags: + - system_early_adopter + - id: prms_76f33deb-dd5d-46b7-b79d-e1f8f0a9a1e0 + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-supporter-tags + data: + tags: + - system_supporter + - id: prms_0d9549db-d30a-48f3-a6b8-6741ce5a4283 + ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b + name: permission-invite-photos + data: {} + - id: prms_153ac0b7-c2dd-43f9-96e3-c61fd2e85509 + ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b + name: permission-profile-pic-override + data: {} + - id: prms_1d9549db-d30a-48f3-a6b8-6741ce5a4283 + ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b + name: permission-user-icons + data: {} + - id: prms_dc02c512-4c03-479c-8c6a-d9329c023baf + ownerId: usr_bc012e97-a292-4abc-b4e6-f9edcc8c0d2b + name: permission-user-gallery + data: {} PermissionResponse: description: Returns a single Permission object. content: From 0c553fc645af775e2eabf4e900da3b93ce8b021d Mon Sep 17 00:00:00 2001 From: Foorack Date: Thu, 26 Aug 2021 13:57:47 +0200 Subject: [PATCH 4/6] 3.0, fix for Models can only have 1 example --- openapi/components/schemas/Permission.yaml | 28 +++++++--------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/openapi/components/schemas/Permission.yaml b/openapi/components/schemas/Permission.yaml index 243523e5..b2661cbe 100644 --- a/openapi/components/schemas/Permission.yaml +++ b/openapi/components/schemas/Permission.yaml @@ -1,15 +1,5 @@ description: '' type: object -x-examples: - example-1: - id: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff - ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b - name: permission-extra-favorites-avatar-groups - data: - maxFavoritesPerGroup: - avatar: 25 - maxFavoriteGroups: - avatar: 4 properties: id: $ref: ./PermissionID.yaml @@ -26,12 +16,12 @@ required: - ownerId - name title: Permission -examples: - - id: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff - ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b - name: permission-extra-favorites-avatar-groups - data: - maxFavoritesPerGroup: - avatar: 25 - maxFavoriteGroups: - avatar: 4 +example: + id: prms_804ba021-9f47-4e25-9847-1f42fdb2e6ff + ownerId: usr_17f19d1e-fd48-493b-a8ad-807a3d8bdd1b + name: permission-extra-favorites-avatar-groups + data: + maxFavoritesPerGroup: + avatar: 25 + maxFavoriteGroups: + avatar: 4 From 85a588a578b26d4ce930067deb480b9e1d453954 Mon Sep 17 00:00:00 2001 From: foorack Date: Thu, 26 Aug 2021 14:01:14 +0200 Subject: [PATCH 5/6] fix: Add missing tag on permission endpoint --- openapi/components/paths/permissions.yaml | 3 ++- openapi/openapi.yaml | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/openapi/components/paths/permissions.yaml b/openapi/components/paths/permissions.yaml index 4509d3ac..4566c6f4 100644 --- a/openapi/components/paths/permissions.yaml +++ b/openapi/components/paths/permissions.yaml @@ -34,7 +34,8 @@ paths: - $ref: '#/components/parameters/permissionId' get: summary: Get Permission - tags: [] + tags: + - permissions responses: '200': $ref: '#/components/responses/PermissionResponse' diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index fa66a1bf..7bf4fd44 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -2669,8 +2669,8 @@ tags: - name: files - name: friends - name: notifications - - name: playermoderation - name: permissions + - name: playermoderation - name: system - name: users - name: worlds From 0bbb00d50c2416d4372908c8c8ef158a609202d5 Mon Sep 17 00:00:00 2001 From: foorack Date: Thu, 26 Aug 2021 14:21:16 +0200 Subject: [PATCH 6/6] Add missing security params --- openapi/components/paths/permissions.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/openapi/components/paths/permissions.yaml b/openapi/components/paths/permissions.yaml index 4566c6f4..8b34585d 100644 --- a/openapi/components/paths/permissions.yaml +++ b/openapi/components/paths/permissions.yaml @@ -8,6 +8,9 @@ paths: get: summary: Get Assigned Permission operationId: getAssignedPermissions + security: + - apiKeyCookie: [] + authCookie: [] responses: '200': $ref: '#/components/responses/PermissionListResponse' @@ -27,6 +30,9 @@ paths: '401': $ref: ../responses/MissingCredentialsError.yaml operationId: getPermissions + security: + - apiKeyCookie: [] + authCookie: [] x-internal: true description: '**REQUIRES INTERNAL ADMIN CREDENTIALS**. Returns a list of all existing permissions, just like `/users` with empty search would.' '/permissions/{permissionId}': @@ -42,6 +48,9 @@ paths: '401': $ref: ../responses/MissingCredentialsError.yaml operationId: getPermission + security: + - apiKeyCookie: [] + authCookie: [] description: 'Returns a single permission. This endpoint is pretty useless, as it returns the exact same information as `/auth/permissions`.' tags: $ref: ../../openapi.yaml#/tags