From 97597ecffe7efe45d1ab9b48987e6519f16a3258 Mon Sep 17 00:00:00 2001 From: LovelessCodes Date: Sun, 10 Nov 2024 00:18:21 +0100 Subject: [PATCH] feat: new references route with openapi spec --- docs/app/reference/route.ts | 9 + docs/public/openapi.yml | 1341 +++++++++++++++++++++++++++++++++++ 2 files changed, 1350 insertions(+) create mode 100644 docs/app/reference/route.ts create mode 100644 docs/public/openapi.yml diff --git a/docs/app/reference/route.ts b/docs/app/reference/route.ts new file mode 100644 index 00000000..781f4e11 --- /dev/null +++ b/docs/app/reference/route.ts @@ -0,0 +1,9 @@ +import { ApiReference } from "@scalar/nextjs-api-reference"; + +const config = { + spec: { + url: "/openapi.yml", + }, +}; + +export const GET = ApiReference(config); diff --git a/docs/public/openapi.yml b/docs/public/openapi.yml new file mode 100644 index 00000000..38d8db3f --- /dev/null +++ b/docs/public/openapi.yml @@ -0,0 +1,1341 @@ +openapi: 3.1.1 +info: + title: Better Auth API + description: | + The Better Auth API Endpoints gets documented here. + + ## Resources + + * https://github.com/better-auth/better-auth + * https://better-auth.com + version: 1.0.0 + contact: + url: https://better-auth.com +servers: + - url: '{protocol}://{baseURL}/{path}' + description: Responds with your request data + variables: + baseURL: + default: 'localhost:3000' + protocol: + enum: + - https + default: https + path: + default: '' +security: + - bearerAuth: [] + - apiKeyCookie: [] +tags: + - name: Sessions + description: Everything about sessions + - name: Account + description: Everything about account + - name: Callback + description: Everything about callback + - name: Email Verification + description: Everything about email verification + - name: Forget Password + description: Everything about forget password + - name: Sign in + description: Everything about sign in + - name: Sign out + description: Everything about sign out + - name: Sign up + description: Everything about sign up + - name: Update user + description: Everything about update user +paths: + '/get-session': + get: + tags: + - Sessions + summary: Get current session + descriptions: It's used to get the currently logged in session. + operationId: getSession + security: + - bearerAuth: [] + - apiKeyCookie: [] + responses: + '200': + description: OK + content: + application/json: + schema: + '$ref': '#/components/schemas/Session' + '401': + description: Unauthorized + content: + application/json: + schema: + '$ref': '#/components/responses/Unauthorized' + '/list-sessions': + get: + tags: + - Sessions + summary: List all sessions + descriptions: It's used to list all the sessions. + operationId: listSessions + security: + - bearerAuth: [] + - apiKeyCookie: [] + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + '$ref': '#/components/schemas/Session' + '401': + description: Unauthorized + content: + application/json: + schema: + '$ref': '#/components/responses/Unauthorized' + '/revoke-session': + post: + tags: + - Sessions + summary: Revoke a session + descriptions: It's used to revoke a session. + operationId: revokeSession + security: + - bearerAuth: [] + - apiKeyCookie: [] + requestBody: + description: Session ID + content: + application/json: + schema: + type: object + properties: + id: + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: boolean + examples: + - true + '401': + description: Unauthorized + content: + application/json: + schema: + '$ref': '#/components/responses/Unauthorized' + '/revoke-sessions': + post: + tags: + - Sessions + summary: Revoke all sessions + descriptions: It's used to revoke all sessions. + operationId: revokeSessions + security: + - bearerAuth: [] + - apiKeyCookie: [] + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: boolean + examples: + - true + '401': + description: Unauthorized + content: + application/json: + schema: + '$ref': '#/components/responses/Unauthorized' + '/revoke-other-sessions': + post: + tags: + - Sessions + summary: Revoke other sessions + descriptions: It's used to revoke all other sessions, other than the current one. + operationId: revokeOtherSessions + security: + - bearerAuth: [] + - apiKeyCookie: [] + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: boolean + examples: + - true + '401': + description: Unauthorized + content: + application/json: + schema: + '$ref': '#/components/responses/Unauthorized' + '/list-accounts': + get: + tags: + - Account + summary: List all accounts + descriptions: It's used to list all the accounts linked to the current user. + operationId: listAccounts + security: + - bearerAuth: [] + - apiKeyCookie: [] + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + '$ref': '#/components/schemas/Account' + '401': + description: Unauthorized + content: + application/json: + schema: + '$ref': '#/components/responses/Unauthorized' + '/link-social': + post: + tags: + - Account + summary: Link social account + descriptions: It's used to link social account to the current user. + operationId: linkSocial + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + currentURL: + name: currentURL + in: query + required: false + schema: + type: string + format: url + examples: + - https://better-auth.com + requestBody: + content: + application/json: + schema: + type: object + properties: + provider: + type: string + examples: + - google + - facebook + - github + - gitlab + - twitter + - linkedin + - microsoft + default: google + callbackURL: + type: string + format: url + required: false + examples: + - https://better-auth.com + default: http://localhost:3000 + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + url: + type: string + format: url + redirect: + type: boolean + examples: + - true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Social Account is already linked. + '401': + description: Unauthorized + content: + application/json: + schema: + '$ref': '#/components/responses/Unauthorized' + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Provider not found + '/callback/:id': + get: + tags: + - Callback + summary: Callback + descriptions: It's used to callback the social account. + operationId: callback + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + id: + name: id + in: path + required: true + schema: + type: string + state: + name: state + in: query + required: true + schema: + type: string + code: + name: code + in: query + required: false + schema: + type: string + error: + name: error + in: query + required: false + schema: + type: string + responses: + '302': + description: Redirect on error or success + '/send-verification-email': + post: + tags: + - Email Verification + summary: Send verification email + descriptions: It's used to send verification email. + operationId: sendVerificationEmail + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + currentURL: + name: currentURL + in: query + required: false + schema: + type: string + format: url + examples: + - https://better-auth.com + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + format: email + examples: + - bekacru@better-auth.com + callbackURL: + type: string + format: url + required: false + examples: + - https://better-auth.com + default: http://localhost:3000 + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: boolean + examples: + - true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Verification email isn't enabled + - User not found + '/verify-email': + get: + tags: + - Email Verification + summary: Verify email + descriptions: It's used to verify email. + operationId: verifyEmail + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + token: + name: token + in: query + required: true + schema: + type: string + format: uuid + callbackURL: + name: callbackURL + in: query + required: false + schema: + type: string + format: url + examples: + - https://better-auth.com + default: http://localhost:3000 + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + user: + '$ref': '#/components/schemas/User' + nullable: true + status: + type: boolean + examples: + - true + '302': + description: Redirect + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Invalid token + - User not found + '401': + description: Unauthorized + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Session not found + - Invalid session + '/forget-password': + post: + tags: + - Forget Password + summary: Forget password + descriptions: It's used to forget password. + operationId: forgetPassword + security: + - bearerAuth: [] + - apiKeyCookie: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + format: email + examples: + - bekacru@better-auth.com + redirctTo: + type: string + format: url + required: false + examples: + - https://better-auth.com + default: http://localhost:3000 + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: boolean + examples: + - true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Reset password isn't enabled + '/reset-password/:token': + get: + tags: + - Forget Password + summary: Reset password with token + descriptions: It's used to reset password with a token. + operationId: resetPasswordToken + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + token: + name: token + in: path + required: true + schema: + type: string + format: uuid + callbackURL: + name: callbackURL + in: query + required: false + schema: + type: string + format: url + examples: + - https://better-auth.com + default: http://localhost:3000 + responses: + '302': + description: Redirect + '/reset-password': + post: + tags: + - Forget Password + summary: Reset password + descriptions: It's used to reset/set a new password. + operationId: resetPassword + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + token: + name: token + in: query + required: true + schema: + type: string + format: uuid + callbackURL: + name: callbackURL + in: query + required: false + schema: + type: string + format: url + examples: + - https://better-auth.com + requestBody: + content: + application/json: + schema: + type: object + properties: + newPassword: + type: string + examples: + - i-love-better-auth + - better-auth-is-cool + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: boolean + examples: + - true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Token not found + - Invalid token + - Failed to update password + '/sign-in/social': + post: + tags: + - Sign in + summary: Sign in with social account + descriptions: It's used to sign in with social account. + operationId: signInSocial + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + currentURL: + name: currentURL + in: query + required: false + schema: + type: string + format: url + examples: + - https://better-auth.com + requestBody: + content: + application/json: + schema: + type: object + properties: + provider: + type: string + examples: + - google + - facebook + - github + - gitlab + - twitter + - linkedin + - microsoft + default: google + callbackURL: + type: string + format: url + required: false + examples: + - https://better-auth.com + default: http://localhost:3000 + idToken: + required: false + type: object + properties: + token: + type: string + nonce: + type: string + required: false + accessToken: + type: string + required: false + refreshToken: + type: string + required: false + expiresAt: + type: integer + format: int64 + required: false + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + user: + '$ref': '#/components/schemas/User' + nullable: true + session: + '$ref': '#/components/schemas/Session' + nullable: true + url: + type: string + format: url + redirect: + type: boolean + examples: + - true + '401': + description: Unauthorized + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Invalid id token + - Failed to get user info + - User email not found + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Provider not found + - Provider does not support id token verification + '/sign-in/email': + post: + tags: + - Sign in + summary: Sign in with email + descriptions: It's used to sign in with email. + operationId: signInEmail + security: + - bearerAuth: [] + - apiKeyCookie: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + format: email + examples: + - bekacru@better-auth.com + password: + type: string + examples: + - i-love-better-auth + callbackURL: + type: string + format: url + required: false + dontRememberMe: + type: boolean + examples: + - true + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + user: + '$ref': '#/components/schemas/User' + nullable: true + session: + '$ref': '#/components/schemas/Session' + nullable: true + url: + type: string + format: url + redirect: + type: boolean + examples: + - true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Invalid email + '401': + description: Unauthorized + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Email and password is not enabled + - Invalid email or password + - Unexpected error + - Failed to create session + '403': + description: Forbidden + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Email is not verified. Check your email for a verification link + '500': + description: Internal Server Error + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Email is not verified. + '/sign-out': + post: + tags: + - Sign out + summary: Sign out + descriptions: It's used to sign out. + operationId: signOut + security: + - bearerAuth: [] + - apiKeyCookie: [] + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: boolean + examples: + - true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Session not found + '/sign-up/email': + post: + tags: + - Sign up + summary: Sign up with email + descriptions: It's used to sign up with email. + operationId: signUpEmail + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + currentURL: + name: currentURL + in: query + required: false + schema: + type: string + format: url + examples: + - https://better-auth.com + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + examples: + - Bekacru + email: + type: string + format: email + examples: + - bekacru@better-auth.com + password: + type: string + examples: + - i-love-better-auth + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + user: + '$ref': '#/components/schemas/User' + session: + '$ref': '#/components/schemas/Session' + nullable: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Email and password sign up is not enabled + - Invalid email + - Password is too short + - Password is too long + - Failed to create user + - Failed to create session + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - User with this email already exists + - Failed to create user + '/update-user': + post: + tags: + - Update user + summary: Update user + descriptions: It's used to update user. + operationId: updateUser + security: + - bearerAuth: [] + - apiKeyCookie: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + required: false + type: string + examples: + - Bekacru + image: + required: false + type: string + format: url + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + user: + '$ref': '#/components/schemas/User' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - You can't update email + '/change-password': + post: + tags: + - Update user + summary: Change password + descriptions: It's used to change password. + operationId: changePassword + security: + - bearerAuth: [] + - apiKeyCookie: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + currentPassword: + type: string + examples: + - i-like-better-auth + newPassword: + type: string + examples: + - i-love-better-auth + revokeOtherSessions: + type: boolean + examples: + - true + responses: + '200': + description: OK + content: + application/json: + schema: + '$ref': '#/components/schemas/User' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Password is too short + - Password too long + - User does not have a password + - Incorrect password + '500': + description: Internal Server Error + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Unable to create session + '/set-password': + post: + tags: + - Update user + summary: Set password + descriptions: It's used to set password. + operationId: setPassword + security: + - bearerAuth: [] + - apiKeyCookie: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + newPassword: + type: string + examples: + - i-love-better-auth + responses: + '200': + description: OK + content: + application/json: + schema: + '$ref': '#/components/schemas/User' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Password is too short + - Password too long + - user already has a password + '/delete-user': + post: + tags: + - Update user + summary: Delete user + descriptions: It's used to delete user. + operationId: deleteUser + security: + - bearerAuth: [] + - apiKeyCookie: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + password: + type: string + examples: + - i-love-better-auth + responses: + '200': + description: OK + content: + application/json: + schema: + type: integer + nullable: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - User does not have a password + - Incorrect password + '/change-email': + post: + tags: + - Update user + summary: Change email + descriptions: It's used to change email. + operationId: changeEmail + security: + - bearerAuth: [] + - apiKeyCookie: [] + parameters: + currentURL: + name: currentURL + in: query + required: false + schema: + type: string + format: url + examples: + - https://better-auth.com + requestBody: + content: + application/json: + schema: + type: object + properties: + newEmail: + type: string + format: email + examples: + - bekacru@better-auth.com + callbackURL: + type: string + format: url + required: false + examples: + - https://better-auth.com + default: http://localhost:3000 + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + user: + '$ref': '#/components/schemas/User' + nullable: true + status: + type: boolean + examples: + - true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + examples: + - Change email is disabled + - Email is the same + - Couldn't update your email + - Verification email isn't enabled +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + description: JWT Bearer token authentication + apiKeyCookie: + type: apiKey + in: cookie + name: api_key + description: API key browser cookie + responses: + BadRequest: + description: Bad Request + content: + application/json: + schema: + '$ref': '#/components/schemas/Error' + Forbidden: + description: Forbidden + content: + application/json: + schema: + '$ref': '#/components/schemas/Error' + NotFound: + description: NotFound + content: + application/json: + schema: + '$ref': '#/components/schemas/Error' + Unauthorized: + description: Unauthorized + content: + application/json: + schema: + '$ref': '#/components/schemas/Error' + schemas: + Session: + type: object + properties: + session: + type: object + properties: + id: + type: string + expiresAt: + type: string + format: date-time + ipAddress: + type: string + format: ipv4 + example: 127.0.0.1 + userAgent: + type: string + userId: + type: string + format: uuid + user: + type: object + properties: + id: + type: string + name: + type: string + email: + type: string + format: email + emailVerified: + type: boolean + image: + type: string + format: url + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + Account: + type: object + properties: + id: + type: string + accountId: + type: string + providerId: + type: string + examples: + - google + - facebook + - github + - gitlab + - twitter + - linkedin + - microsoft + userId: + type: string + accessToken: + type: string + refreshToken: + type: string + idToken: + type: string + expiresAt: + type: string + format: date-time + password: + type: string + User: + type: object + properties: + id: + type: string + name: + type: string + email: + type: string + format: email + emailVerified: + type: boolean + image: + type: string + format: url + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + Error: + type: object + description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) + properties: + type: + type: string + examples: + - https://example.com/errors/generic-error + title: + type: string + examples: + - Something went wrong here. + status: + type: integer + format: int64 + examples: + - 403 + detail: + type: string + examples: + - Unfortunately, we can’t provide further information. \ No newline at end of file