feat(openapi): document error responses and undocumented schema fields

openapi/components/parameters.yaml

@@ -261,6 +261,13 @@
   in: path
   schema:
     $ref: ./schemas/FavoriteType.yaml
+favoriteGroupTypeQuery:
+  name: type
+  description: Filter the returned groups to a single favourite type.
+  required: false
+  in: query
+  schema:
+    $ref: ./schemas/FavoriteType.yaml
 favoriteId:
   name: favoriteId
   description: Must be a valid favorite ID.
@@ -301,12 +308,12 @@
   in: query
   schema:
     $ref: ./schemas/UserID.yaml
 fuzzy:
   name: fuzzy
   required: false
   in: query
   schema:
     type: boolean
 groupByDuration:
   name: groupByDuration
   description: Time bucket size for economy metrics. Observed values include `days` and `years`.
@@ -645,12 +652,12 @@
   schema:
     type: string
     format: date-time
 mostRecentFlag:
   name: mostRecent
   required: false
   in: query
   schema:
     type: boolean
 noplatform:
   name: noplatform
   description: The platform the asset does not support.
@@ -783,7 +790,7 @@
     type: string
 sellerId:
   name: sellerId
-  description: Seller to retrieve economy metrics for.
+  description: Seller to scope the results to.
   required: true
   in: query
   schema:
@@ -818,6 +825,13 @@
   in: query
   schema:
     $ref: ./schemas/SortOptionProductPurchase.yaml
+ssoProvider:
+  name: provider
+  description: The third-party service to mint a token for.
+  required: true
+  in: path
+  schema:
+    $ref: ./schemas/SsoProvider.yaml
 startDate:
   name: startDate
   description: The start date of the search range.
@@ -834,18 +848,18 @@
   schema:
     type: string
     example: game night
 storeId:
   name: storeId
   required: true
   in: query
   schema:
     $ref: ./schemas/StoreID.yaml
 storeView:
   name: fetch
   required: false
   in: query
   schema:
     $ref: ./schemas/StoreView.yaml
 submitterId:
   name: submitterId
   description: Must be a valid user ID.

openapi/components/paths.yaml

@@ -314,6 +314,8 @@
   $ref: "./paths/notifications.yaml#/paths/~1notifications~1{notificationId}~1respond"
 "/notifications/{notificationId}/see":
   $ref: "./paths/notifications.yaml#/paths/~1notifications~1{notificationId}~1see"
+/oauth/redirectCode:
+  $ref: "./paths/authentication.yaml#/paths/~1oauth~1redirectCode"
 /permissions:
   $ref: "./paths/miscellaneous.yaml#/paths/~1permissions"
 "/permissions/{permissionId}":
@@ -344,6 +346,8 @@
   $ref: "./paths/invite.yaml#/paths/~1requestInvite~1{userId}~1photo"
 /reward/redeem:
   $ref: "./paths/inventory.yaml#/paths/~1reward~1redeem"
+"/sso/{provider}":
+  $ref: "./paths/authentication.yaml#/paths/~1sso~1{provider}"
 /subscriptions:
   $ref: "./paths/economy.yaml#/paths/~1subscriptions"
 /tilia/status:
@@ -458,13 +462,13 @@
   $ref: "./paths/worlds.yaml#/paths/~1worlds~1{worldId}"
 "/worlds/{worldId}/addTags":
   $ref: "./paths/worlds.yaml#/paths/~1worlds~1{worldId}~1addTags"
+"/worlds/{worldId}/deleteTags":
+  $ref: "./paths/worlds.yaml#/paths/~1worlds~1{worldId}~1deleteTags"
 "/worlds/{worldId}/metadata":
   $ref: "./paths/worlds.yaml#/paths/~1worlds~1{worldId}~1metadata"
 "/worlds/{worldId}/platform/{publishedPlatform}":
   $ref: "./paths/worlds.yaml#/paths/~1worlds~1{worldId}~1platform~1{publishedPlatform}"
 "/worlds/{worldId}/publish":
   $ref: "./paths/worlds.yaml#/paths/~1worlds~1{worldId}~1publish"
-"/worlds/{worldId}/removeTags":
-  $ref: "./paths/worlds.yaml#/paths/~1worlds~1{worldId}~1removeTags"
 "/worlds/{worldId}/{instanceId}":
   $ref: "./paths/worlds.yaml#/paths/~1worlds~1{worldId}~1{instanceId}"

openapi/components/paths/authentication.yaml

@@ -79,7 +79,7 @@
           $ref: ../responses/MissingCredentialsError.yaml
   /auth/twofactorauth:
     delete:
       operationId: disable2FA
       summary: Disable 2FA
       description: Disables 2FA for the currently logged in account
       tags:
@@ -93,7 +93,7 @@
           $ref: ../responses/MissingCredentialsError.yaml
   /auth/twofactorauth/emailotp/verify:
     post:
       operationId: verify2FAEmailCode
       summary: Verify 2FA email code
       description: Finishes the login sequence with an 2FA email code.
       tags:
@@ -136,7 +136,7 @@
           $ref: ../responses/MissingCredentialsError.yaml
   /auth/twofactorauth/totp/pending:
     delete:
       operationId: cancelPending2FA
       summary: Cancel pending enabling of time-based 2FA codes
       description: Cancels the sequence for enabling time-based 2FA.
       tags:
@@ -150,7 +150,7 @@
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
     post:
       operationId: enable2FA
       summary: Enable time-based 2FA codes
       description: Begins the sequence for enabling time-based 2FA.
       tags:
@@ -165,7 +165,7 @@
           $ref: ../responses/MissingCredentialsError.yaml
   /auth/twofactorauth/totp/pending/verify:
     post:
       operationId: verifyPending2FA
       summary: Verify Pending 2FA code
       description: Finishes sequence for enabling time-based 2FA.
       tags:
@@ -187,7 +187,7 @@
           $ref: ../responses/MissingCredentialsError.yaml
   /auth/twofactorauth/totp/verify:
     post:
       operationId: verify2FA
       summary: Verify 2FA code
       description: Finishes the login sequence with a normal 2FA-generated code for accounts with 2FA-protection enabled.
       tags:
@@ -252,7 +252,7 @@
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
     get:
       operationId: getGlobalAvatarModerations
       summary: Get Global Avatar Moderations
       description: Returns list of globally moderated avatars.
       tags:
@@ -399,6 +399,38 @@
           $ref: ../responses/MissingCredentialsError.yaml
         "403":
           $ref: ../responses/InvalidAdminCredentialsError.yaml
+  /oauth/redirectCode:
+    get:
+      operationId: getOAuthRedirectCode
+      summary: Get OAuth Redirect Code
+      description: Mints a short-lived code that hands the current session to an OAuth redirect.
+      tags:
+        - authentication
+      security:
+        - authCookie: []
+      responses:
+        "200":
+          $ref: ../responses/authentication/OAuthRedirectCodeResponse.yaml
+        "401":
+          $ref: ../responses/MissingCredentialsError.yaml
+  "/sso/{provider}":
+    parameters:
+      - $ref: ../parameters.yaml#/ssoProvider
+    get:
+      operationId: getSsoToken
+      summary: Get SSO Token
+      description: Returns a token for the given third-party service.
+      tags:
+        - authentication
+      security:
+        - authCookie: []
+      responses:
+        "200":
+          $ref: ../responses/authentication/SsoTokenResponse.yaml
+        "400":
+          $ref: ../responses/authentication/SsoProviderUnsupportedError.yaml
+        "401":
+          $ref: ../responses/MissingCredentialsError.yaml
   "/users/{userId}/delete":
     parameters:
       - $ref: ../parameters.yaml#/userId
@@ -416,8 +448,8 @@
       security:
         - authCookie: []
       responses:
         "200":
           $ref: ../responses/authentication/DeleteUserResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
 components:

openapi/components/paths/avatars.yaml

@@ -6,7 +6,7 @@
 paths:
   /avatarStyles:
     get:
       operationId: getAvatarStyles
       summary: Get Avatar Styles
       description: List avatar styles.
       tags:
@@ -16,9 +16,11 @@
           $ref: ../responses/avatars/AvatarStyleListResponse.yaml
   /avatars:
     get:
       operationId: searchAvatars
       summary: Search Avatars
-      description: Search and list avatars by query filters. You can only search your own or featured avatars. It is not possible as a normal user to search other peoples avatars.
+      description: Search and list avatars by query filters. You can only search your
+        own or featured avatars. It is not possible as a normal user to search
+        other peoples avatars.
       tags:
         - avatars
       parameters:
@@ -53,7 +55,9 @@
     post:
       operationId: createAvatar
       summary: Create Avatar
-      description: Create an avatar. It's possible to optionally specify a ID if you want a custom one. Attempting to create an Avatar with an already claimed ID will result in a DB error.
+      description: Create an avatar. It's possible to optionally specify a ID if you
+        want a custom one. Attempting to create an Avatar with an already
+        claimed ID will result in a DB error.
       tags:
         - avatars
       requestBody:
@@ -143,8 +147,8 @@
       security:
         - authCookie: []
       responses:
         "200":
           $ref: ../responses/avatars/AvatarResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
         "404":
@@ -158,21 +162,25 @@
       requestBody:
         content:
           application/json:
             schema:
               $ref: ../requests/UpdateAvatarRequest.yaml
       security:
         - authCookie: []
       responses:
         "200":
           $ref: ../responses/avatars/AvatarResponse.yaml
+        "400":
+          $ref: ../responses/RequestValidationError.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
         "404":
           $ref: ../responses/avatars/AvatarNotFoundError.yaml
     delete:
       operationId: deleteAvatar
       summary: Delete Avatar
-      description: 'Delete an avatar. Notice an avatar is never fully "deleted", only its ReleaseStatus is set to "hidden" and the linked Files are deleted. The AvatarID is permanently reserved.'
+      description: 'Delete an avatar. Notice an avatar is never fully "deleted", only
+        its ReleaseStatus is set to "hidden" and the linked Files are deleted.
+        The AvatarID is permanently reserved.'
       tags:
         - avatars
       security:
@@ -243,7 +251,6 @@
       - $ref: ../parameters.yaml#/avatarId
     put:
       operationId: selectFallbackAvatar
-      deprecated: true
       summary: Select Fallback Avatar
       description: Switches into that avatar as your fallback avatar.
       tags:
@@ -265,7 +272,8 @@
     get:
       operationId: getOwnAvatar
       summary: Get Own Avatar
-      description: Get the current avatar for the user. This will return an error for any other user than the one logged in.
+      description: Get the current avatar for the user. This will return an error for
+        any other user than the one logged in.
       tags:
         - avatars
       security:

openapi/components/paths/calendar.yaml

@@ -46,6 +46,7 @@ paths:
         - $ref: ../parameters.yaml#/number
         - $ref: ../parameters.yaml#/calendarDiscoveryNextCursor
       security:
+        - {}
         - authCookie: []
       responses:
         "200":
@@ -64,6 +65,7 @@ paths:
         - $ref: ../parameters.yaml#/number
         - $ref: ../parameters.yaml#/offset
       security:
+        - {}
         - authCookie: []
       responses:
         "200":