diff --git a/openapi/components/parameters.yaml b/openapi/components/parameters.yaml index b53bdf61..8a8327cb 100644 --- a/openapi/components/parameters.yaml +++ b/openapi/components/parameters.yaml @@ -111,6 +111,34 @@ userId: required: true schema: type: string +userIdQuery: + name: userId + in: query + required: false + schema: + type: string + description: Filter by UserID. +excludeUserId: + name: excludeUserId + in: query + required: false + schema: + type: string + description: Exclude by UserID. +displayName: + name: displayName + in: query + required: false + schema: + type: string + description: Filter by displayName. +email: + name: email + in: query + required: false + schema: + type: string + description: Filter by email. maxUnityVersion: name: maxUnityVersion in: query @@ -153,13 +181,6 @@ search: schema: type: string description: Filters by world name. -userIdQuery: - name: userId - in: query - required: false - schema: - type: string - description: Filter by author UserID featured: name: featured in: query diff --git a/openapi/components/paths.yaml b/openapi/components/paths.yaml index 538199fa..7c4cf8c4 100644 --- a/openapi/components/paths.yaml +++ b/openapi/components/paths.yaml @@ -4,6 +4,8 @@ $ref: ./paths/authentication.yaml#/paths/~1logout /auth/user: $ref: ./paths/authentication.yaml#/paths/~1auth~1user +/auth/exists: + $ref: ./paths/authentication.yaml#/paths/~1auth~1exists /auth/twofactorauth/totp/verify: $ref: ./paths/authentication.yaml#/paths/~1auth~1twofactorauth~1totp~1verify /auth/twofactorauth/otp/verify: diff --git a/openapi/components/paths/authentication.yaml b/openapi/components/paths/authentication.yaml index 976c2118..4fd9bc54 100644 --- a/openapi/components/paths/authentication.yaml +++ b/openapi/components/paths/authentication.yaml @@ -111,6 +111,28 @@ paths: - authHeader: [] twoFactorAuthCookie: [] - authCookie: [] + /auth/exists: + get: + summary: Check User Exists + tags: + - authentication + responses: + '200': + $ref: ../responses/authentication/UserExistsResponse.yaml + '400': + $ref: ../responses/authentication/MissingParameterError.yaml + operationId: checkUserExists + parameters: + - $ref: ../parameters.yaml#/email + - $ref: ../parameters.yaml#/displayName + - $ref: ../parameters.yaml#/userIdQuery + - $ref: ../parameters.yaml#/excludeUserId + description: |- + Checks if a user by a given `username`, `displayName` or `email` exist. This is used during registration to check if a username has already been taken, during change of displayName to check if a displayName is available, and during change of email to check if the email is already used. In the later two cases the `excludeUserId` is used to exclude oneself, otherwise the result would always be true. + + It is **REQUIRED** to include **AT LEAST** `username`, `displayName` **or** `email` query parameter. Although they can be combined - in addition with `excludeUserId` (generally to exclude yourself) - to further fine-tune the search. + security: + - apiKeyCookie: [] /auth/twofactorauth/totp/verify: post: summary: Verify 2FA code diff --git a/openapi/components/paths/worlds.yaml b/openapi/components/paths/worlds.yaml index 004275e3..14da0924 100644 --- a/openapi/components/paths/worlds.yaml +++ b/openapi/components/paths/worlds.yaml @@ -212,6 +212,8 @@ paths: '404': $ref: ../responses/worlds/WorldNotFoundError.yaml description: Get information about a specific World. + security: + - apiKeyCookie: [] put: summary: Update World operationId: updateWorld diff --git a/openapi/components/responses/authentication/MissingParameterError.yaml b/openapi/components/responses/authentication/MissingParameterError.yaml new file mode 100644 index 00000000..94c66919 --- /dev/null +++ b/openapi/components/responses/authentication/MissingParameterError.yaml @@ -0,0 +1,11 @@ +description: Error response when missing at least 1 of the required parameters. +content: + application/json: + schema: + $ref: ../../schemas/Error.yaml + examples: + 400 At Least One Parameter Required: + value: + error: + message: "\"username, email, or displayName required\"" + status_code: 400 \ No newline at end of file diff --git a/openapi/components/responses/authentication/UserExistsResponse.yaml b/openapi/components/responses/authentication/UserExistsResponse.yaml new file mode 100644 index 00000000..8a8c71e4 --- /dev/null +++ b/openapi/components/responses/authentication/UserExistsResponse.yaml @@ -0,0 +1,5 @@ +description: Returns a response if a user exists or not. +content: + application/json: + schema: + $ref: ../../schemas/UserExists.yaml diff --git a/openapi/components/schemas/UserExists.yaml b/openapi/components/schemas/UserExists.yaml new file mode 100644 index 00000000..be9b9ffe --- /dev/null +++ b/openapi/components/schemas/UserExists.yaml @@ -0,0 +1,10 @@ +title: UserExists +type: object +description: 'Status object representing if a queried user by username or userId exists or not. This model is primarily used by the `/auth/exists` endpoint, which in turn is used during registration. Please see the documentation on that endpoint for more information on usage.' +properties: + userExists: + type: boolean + description: Status if a user exist with that username or userId. + default: false +required: + - userExists