From a231558ac65073277a6198602da60511c0598630 Mon Sep 17 00:00:00 2001 From: foorack Date: Thu, 23 Sep 2021 22:56:33 +0200 Subject: [PATCH 1/3] feature: add `checkUserExists` via `/auth/exists` endpoint to search for username/displayName/email --- openapi/components/parameters.yaml | 35 +++++++++++++++---- openapi/components/paths/authentication.yaml | 21 +++++++++++ openapi/components/paths/worlds.yaml | 2 ++ .../authentication/MissingParameterError.yaml | 11 ++++++ .../authentication/UserExistsResponse.yaml | 5 +++ openapi/components/schemas/UserExists.yaml | 10 ++++++ 6 files changed, 77 insertions(+), 7 deletions(-) create mode 100644 openapi/components/responses/authentication/MissingParameterError.yaml create mode 100644 openapi/components/responses/authentication/UserExistsResponse.yaml create mode 100644 openapi/components/schemas/UserExists.yaml 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/authentication.yaml b/openapi/components/paths/authentication.yaml index 976c2118..f69fdca8 100644 --- a/openapi/components/paths/authentication.yaml +++ b/openapi/components/paths/authentication.yaml @@ -218,6 +218,27 @@ paths: security: - apiKeyCookie: [] authCookie: [] + /auth/exists: + get: + summary: Check If User Exists + tags: [] + 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: [] tags: $ref: ../tags.yaml components: 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 From 7bb5d98340fce072b8b009ad90a462623480e331 Mon Sep 17 00:00:00 2001 From: foorack Date: Thu, 23 Sep 2021 23:06:05 +0200 Subject: [PATCH 2/3] fix: add missing path and tag to `/auth/exists` endpoint --- openapi/components/paths.yaml | 2 + openapi/components/paths/authentication.yaml | 43 ++++++++++---------- 2 files changed, 24 insertions(+), 21 deletions(-) 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 f69fdca8..6fab993a 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 If 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 @@ -218,27 +240,6 @@ paths: security: - apiKeyCookie: [] authCookie: [] - /auth/exists: - get: - summary: Check If User Exists - tags: [] - 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: [] tags: $ref: ../tags.yaml components: From 2bd531adb3b60d636889bb4f864ee06151c74f75 Mon Sep 17 00:00:00 2001 From: foorack Date: Thu, 23 Sep 2021 23:12:04 +0200 Subject: [PATCH 3/3] fix: minor langauge change in `checkUserExists` title --- openapi/components/paths/authentication.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/components/paths/authentication.yaml b/openapi/components/paths/authentication.yaml index 6fab993a..4fd9bc54 100644 --- a/openapi/components/paths/authentication.yaml +++ b/openapi/components/paths/authentication.yaml @@ -113,7 +113,7 @@ paths: - authCookie: [] /auth/exists: get: - summary: Check If User Exists + summary: Check User Exists tags: - authentication responses: