From 8139cc22b752519369af435f377f86502f87ac82 Mon Sep 17 00:00:00 2001 From: Stefan Jacobi Date: Mon, 22 Jan 2024 11:00:55 +0100 Subject: [PATCH] fix(admin api): sync with docs spec --- docs/static/spec/admin.yaml | 565 ++++++++++++++++-------------------- 1 file changed, 249 insertions(+), 316 deletions(-) diff --git a/docs/static/spec/admin.yaml b/docs/static/spec/admin.yaml index f3636a3f0..45054f8fc 100644 --- a/docs/static/spec/admin.yaml +++ b/docs/static/spec/admin.yaml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: - version: 0.9.1 - title: Hanko Admin API + version: "0.9.1" + title: "Hanko Admin API" description: | ## Introduction @@ -12,104 +12,102 @@ info: The Admin API must be protected by an access management system. --- + contact: email: developers@hanko.io license: - url: 'https://www.gnu.org/licenses/agpl-3.0.txt' name: AGPL-3.0-or-later + url: https://www.gnu.org/licenses/agpl-3.0.txt +externalDocs: + description: More about Hanko + url: https://github.com/teamhanko/hanko servers: - - url: 'localhost:8001' + - url: "http://localhost:8001" paths: /: get: - tags: - - Status summary: Status page description: Return information about the API status. Returns a 500 if there are issues with database connectivity. operationId: status + tags: + - Status responses: - '200': - description: API is running + "200": + description: "API is running" content: text/html: schema: type: string - '500': - description: API is not functioning properly + "500": + description: "API is not functioning properly" content: text/html: schema: type: string - servers: - - url: 'localhost:8001' /users: get: + summary: "Get a list of users" + operationId: listUsers tags: - User Management - summary: Get a list of users - operationId: listUsers parameters: - - name: page - in: query - description: The page which should be returned + - in: query + name: page schema: type: integer default: 1 - - name: per_page - in: query - description: The number of returned items + description: The page which should be returned + - in: query + name: per_page schema: type: integer default: 20 - - name: user_id - in: query - description: Only users with the specified user_id are included + description: The number of returned items + - in: query + name: user_id schema: allOf: - - $ref: '#/components/schemas/UUID4' + - $ref: "#/components/schemas/UUID4" example: c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c - - name: email - in: query - description: Only users with the specified email are included + description: Only users with the specified user_id are included + - in: query + name: email schema: type: string format: email example: example@example.com - - name: sort_direction - in: query - description: The sort direction of the returned list (always sorted by created_at) + description: Only users with the specified email are included + - in: query + name: sort_direction schema: type: string enum: - asc - desc + description: The sort direction of the returned list (always sorted by created_at) responses: - '200': - description: Details about users + "200": + description: "Details about users" content: application/json: schema: type: array items: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" headers: X-Total-Count: - schema: - $ref: '#/components/schemas/X-Total-Count' + $ref: "#/components/headers/X-Total-Count" Link: - schema: - $ref: '#/components/schemas/Link' - '400': - $ref: '#/components/responses/BadRequest' - '500': - $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' + $ref: "#/components/headers/Link" + "500": + $ref: "#/components/responses/InternalServerError" + "400": + $ref: "#/components/responses/BadRequest" post: - tags: - - User Management summary: Create a new user operationId: createUser + tags: + - User Management requestBody: content: application/json: @@ -119,10 +117,10 @@ paths: id: description: The ID of the new user allOf: - - $ref: '#/components/schemas/UUID4' + - $ref: "#/components/schemas/UUID4" emails: - type: array description: The email addresses of the new user + type: array items: type: object properties: @@ -136,122 +134,116 @@ paths: - address - is_primary created_at: - type: string description: Time of creation of the user + type: string format: date-time required: - emails responses: - '200': - description: Details of the newly created user + "200": + description: "Details of the newly created user" content: application/json: schema: - $ref: '#/components/schemas/User' - '400': - $ref: '#/components/responses/BadRequest' - '409': - $ref: '#/components/responses/Conflict' - '500': - $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' - '/users/{id}': + $ref: "#/components/schemas/User" + "400": + $ref: "#/components/responses/BadRequest" + "409": + $ref: "#/components/responses/Conflict" + "500": + $ref: "#/components/responses/InternalServerError" + /users/{id}: delete: + summary: "Delete a user by ID" + operationId: deleteUser tags: - User Management - summary: Delete a user by ID - operationId: deleteUser parameters: - name: id in: path description: ID of the user required: true schema: - $ref: '#/components/schemas/UUID4' + $ref: "#/components/schemas/UUID4" responses: - '204': - description: Deleted - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' + "204": + description: "Deleted" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" get: + summary: "Get a user by ID" + operationId: getUser tags: - User Management - summary: Get a user by ID - operationId: getUser parameters: - name: id in: path description: ID of the user required: true schema: - $ref: '#/components/schemas/UUID4' + $ref: "#/components/schemas/UUID4" responses: - '200': - description: Details about the user + "200": + description: "Details about the user" content: application/json: schema: - $ref: '#/components/schemas/User' - '400': - $ref: '#/components/responses/BadRequest' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' + $ref: "#/components/schemas/User" + "400": + $ref: "#/components/responses/BadRequest" + "404": + $ref: "#/components/responses/NotFound" + "500": + $ref: "#/components/responses/InternalServerError" /audit_logs: get: + summary: "Get a list of audit logs" + operationId: listAuditLogs tags: - Audit Logs - summary: Get a list of audit logs - operationId: listAuditLogs parameters: - - name: page - in: query - description: The page which should be returned + - in: query + name: page schema: type: integer default: 1 - - name: per_page - in: query - description: The number of returned items + description: The page which should be returned + - in: query + name: per_page schema: type: integer default: 20 - - name: start_time - in: query - description: Date and time from which the logs are included + description: The number of returned items + - in: query + name: start_time schema: type: string - example: '2022-09-12T12:48:48Z' - - name: end_time - in: query - description: Date and time to which the logs are included + example: 2022-09-12T12:48:48Z + description: Date and time from which the logs are included + - in: query + name: end_time schema: type: string - example: '2022-09-15T12:48:48Z' - - name: actor_user_id - in: query - description: Only audit logs with the specified user_id are included + example: 2022-09-15T12:48:48Z + description: Date and time to which the logs are included + - in: query + name: actor_user_id schema: - allOf: [] + allOf: + - $ref: "#/components/schemas/UUID4" example: c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c - - name: actor_email - in: query - description: Only audit logs with the specified email are included + description: Only audit logs with the specified user_id are included + - in: query + name: actor_email schema: type: string format: email example: example@example.com - - name: meta_source_ip - in: query - description: Only audit logs with the specified ip address are included + description: Only audit logs with the specified email are included + - in: query + name: meta_source_ip schema: allOf: - type: string @@ -259,62 +251,54 @@ paths: - type: string format: ipv6 example: 127.0.0.1 - - name: q - in: query - description: Only audit logs are included when the search string matches values in meta_source_ip or actor_user_id or actor_email + description: Only audit logs with the specified ip address are included + - in: query + name: q schema: type: string example: example.com - - name: type - in: query - description: Only audit logs with the specified type are included - style: form - explode: true + description: Only audit logs are included when the search string matches values in meta_source_ip or actor_user_id or actor_email + - in: query + name: type schema: type: array items: allOf: - - $ref: '#/components/schemas/AuditLogTypes' + - $ref: "#/components/schemas/AuditLogTypes" example: user_created + style: form + explode: true + description: Only audit logs with the specified type are included responses: - '200': - description: Details about audit logs + "200": + description: "Details about audit logs" content: application/json: schema: type: array items: - $ref: '#/components/schemas/AuditLog' + $ref: "#/components/schemas/AuditLog" headers: X-Total-Count: - schema: - $ref: '#/components/schemas/X-Total-Count' + $ref: "#/components/headers/X-Total-Count" Link: - schema: - $ref: '#/components/schemas/Link' - '500': - $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' + $ref: "#/components/headers/Link" + "500": + $ref: "#/components/responses/InternalServerError" /metrics: get: + summary: "Get Prometheus metrics." + operationId: getMetrics tags: - Metrics - summary: Get Prometheus metrics. - operationId: getMetrics responses: - '200': - description: 'Prometheus Metrics for details about the format see: https://prometheus.io/docs/instrumenting/exposition_formats/#text-format-details' + "200": + description: "Prometheus Metrics for details about the format see: https://prometheus.io/docs/instrumenting/exposition_formats/#text-format-details" content: text/plain: schema: type: string example: 'go_gc_duration_seconds{quantile="0"} 2.5875e-05' - examples: - default: - value: 'go_gc_duration_seconds{quantile="0"} 2.5875e-05' - servers: - - url: 'localhost:8001' /webhooks: get: summary: Get a list of webhooks @@ -338,8 +322,6 @@ paths: $ref: '#/components/schemas/Webhook' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' post: summary: Create a new database webhook description: '' @@ -360,8 +342,6 @@ paths: $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' '/webhooks/{id}': get: summary: Get a webhook by ID @@ -381,8 +361,6 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' delete: summary: Delete a webhook by ID operationId: delete-webhooks-id @@ -397,8 +375,6 @@ paths: $ref: '#/components/responses/NotFound' '500': description: Internal Server Error - servers: - - url: 'localhost:8001' put: summary: Update a webhook by ID operationId: put-webhooks-id @@ -429,8 +405,6 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' '/users/{id}/emails': get: summary: Get a list of emails for a user @@ -450,8 +424,6 @@ paths: $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' post: summary: Create an email for a user operationId: post-users-id-emails @@ -474,9 +446,7 @@ paths: $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' - '/users/emails/{email_id}': + '/users/{id}/emails/{email_id}': get: summary: Get an email of a user operationId: get-users-id-emails-email_id @@ -501,8 +471,6 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' delete: summary: Remove an email from a user operationId: delete-users-emails-email_id @@ -525,13 +493,12 @@ paths: $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' - '/users/emails/{email_id}/set_primary': + '/users/{id}/emails/{email_id}/set_primary': post: summary: Set email as primary operationId: post-users-emails-email_id-set_primary parameters: + - $ref: '#/components/parameters/Id' - name: email_id in: path required: true @@ -546,11 +513,6 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' - servers: - - url: 'localhost:8001' -externalDocs: - url: 'https://github.com/teamhanko/hanko' - description: More about Hanko components: parameters: Id: @@ -584,45 +546,37 @@ components: content: application/json: schema: - $ref: '#/components/schemas/Error' - examples: - default: - value: - code: 400 - message: Bad Request + $ref: "#/components/schemas/Error" + example: + code: 400 + message: Bad Request Conflict: description: Conflict content: application/json: schema: - $ref: '#/components/schemas/Error' - examples: - default: - value: - code: 409 - message: Conflict + $ref: "#/components/schemas/Error" + example: + code: 409 + message: Conflict InternalServerError: description: Internal server error content: application/json: schema: - $ref: '#/components/schemas/Error' - examples: - default: - value: - code: 500 - message: Internal Server Error + $ref: "#/components/schemas/Error" + example: + code: 500 + message: Internal Server Error NotFound: description: Not Found content: application/json: schema: - $ref: '#/components/schemas/Error' - examples: - default: - value: - code: 404 - message: Not found + $ref: "#/components/schemas/Error" + example: + code: 404 + message: Not found schemas: UUID4: type: string @@ -630,202 +584,163 @@ components: example: c339547d-e17d-4ba7-8a1d-b3d5a4d17c1c User: type: object + required: + - id + - created_at + - updated_at properties: id: description: The ID of the user allOf: - - $ref: '#/components/schemas/UUID4' + - $ref: "#/components/schemas/UUID4" created_at: - type: string description: Time of creation of the user + type: string format: date-time updated_at: - type: string description: Time of last update of the user + type: string format: date-time webauthn_credentials: - type: array description: List of registered Webauthn credentials + type: array items: - $ref: '#/components/schemas/WebAuthnCredential' + $ref: "#/components/schemas/WebAuthnCredential" emails: - type: array description: List of emails associated to the user + type: array items: $ref: '#/components/schemas/Email' + WebAuthnCredential: + type: object required: - id + - public_key + - attestation_type + - aaguid - created_at - - updated_at - WebAuthnCredential: - type: object properties: id: description: The ID of the credential allOf: - - $ref: '#/components/schemas/UUID4' + - $ref: "#/components/schemas/UUID4" name: - type: string description: A name that the user choose - public_key: type: string + public_key: description: The public key of the credential - attestation_type: type: string + attestation_type: description: The attestation type the credential was registered with - aaguid: type: string + aaguid: description: The AAGUID of the authenticator the credentials was created on + type: string transports: - type: array description: The ways the authenticator is connected + type: array items: type: string created_at: - type: string description: Time of creation of the credential + type: string format: date-time + Email: + type: object required: - id - - public_key - - attestation_type - - aaguid + - address + - is_verified + - is_primary - created_at - Email: - type: object + - updated_at properties: id: description: The ID of the email allOf: - - $ref: '#/components/schemas/UUID4' + - $ref: "#/components/schemas/UUID4" address: - type: string description: The email address + type: string format: email is_verified: - type: boolean description: Indicated the email has been verified. - is_primary: type: boolean + is_primary: description: Indicates it's the primary email address. + type: boolean created_at: - type: string description: Time of creation of the email + type: string format: date-time updated_at: - type: string description: Time of last update of the email + type: string format: date-time + AuditLog: + type: object required: - id - - address - - is_verified - - is_primary + - type + - meta_http_request_id + - meta_source_ip + - meta_user_agent - created_at - updated_at - X-Total-Count: - id: 6ef76076b0d75 - key: X-Total-Count - name: X-Total-Count - style: simple - description: The total count of the requested resource considering query parameter - encodings: [] - examples: - - $ref: '#/components/schemas/__default' - schema: - $ref: '#/components/schemas/6aaa8eaca35df' - __default: - id: d37d1ee8c4488 - key: __default - value: '; rel="first",; rel="last",; rel="next",; rel="prev"' - name: __default - 6aaa8eaca35df: - type: string - Link: - id: 80a3f2b4bcc78 - key: Link - name: Link - style: simple - description: Web Linking as described in RFC5988 - encodings: [] - examples: - - $ref: '#/components/schemas/__default' - schema: - $ref: '#/components/schemas/6aaa8eaca35df' - AuditLogTypes: - type: string - enum: - - user_created - - password_set_succeeded - - password_set_failed - - password_login_succeeded - - password_login_failed - - passcode_login_init_succeeded - - passcode_login_init_failed - - passcode_login_final_succeeded - - passcode_login_final_failed - - webauthn_registration_init_succeeded - - webauthn_registration_init_failed - - webauthn_registration_final_succeeded - - webauthn_registration_final_failed - - webauthn_authentication_init_succeeded - - webauthn_authentication_init_failed - - webauthn_authentication_final_succeeded - - webauthn_authentication_final_failed - - thirdparty_signup_succeeded - - thirdparty_signin_succeeded - description: The type of the audit log - AuditLog: - type: object properties: id: description: The ID of the audit log allOf: - - $ref: '#/components/schemas/UUID4' + - $ref: "#/components/schemas/UUID4" type: allOf: - - $ref: '#/components/schemas/AuditLogTypes' + - $ref: "#/components/schemas/AuditLogTypes" error: - type: string description: A more detailed message why something failed - meta_http_request_id: type: string + meta_http_request_id: description: The ID of the corresponding http request + type: string example: 0a2xsrhlhiQv49FIpq8KV8uQVq6ky9Bw meta_source_ip: - type: string description: The IP from where the http request came from + type: string format: ip-address example: 172.27.0.1 meta_user_agent: - type: string description: The user agent from where the http request came from + type: string actor_user_id: description: The userID from the actor allOf: - - $ref: '#/components/schemas/UUID4' + - $ref: "#/components/schemas/UUID4" actor_email: - type: string description: The email from the actor + type: string format: email created_at: - type: string description: Time of creation of the audit log - format: date-time - example: '2022-09-14T12:15:09.788784Z' - updated_at: type: string - description: Time of last update of the audit log format: date-time - example: '2022-09-14T12:15:09.788784Z' - required: - - id - - type - - meta_http_request_id - - meta_source_ip - - meta_user_agent - - created_at - - updated_at + example: "2022-09-14T12:15:09.788784Z" + DatabaseWebhookEvent: + type: object + title: DatabaseWebhookEvent + properties: + id: + type: string + format: uuid + event: + type: string + enum: + - user + - user.create + - user.delete + - user.update + - user.update.email + - user.update.email.create + - user.update.email.delete + - user.update.email.primary DatabaseWebhook: type: object title: DatabaseWebhook @@ -852,26 +767,10 @@ components: type: string format: date-time updated_at: + description: Time of last update of the audit log type: string format: date-time - DatabaseWebhookEvent: - type: object - title: DatabaseWebhookEvent - properties: - id: - type: string - format: uuid - event: - type: string - enum: - - user - - user.create - - user.delete - - user.update - - user.update.email - - user.update.email.create - - user.update.email.delete - - user.update.email.primary + example: "2022-09-14T12:15:09.788784Z" Webhook: type: object title: Webhook @@ -898,12 +797,46 @@ components: - events Error: type: object + required: + - code + - message properties: code: type: integer format: int32 message: type: string - required: - - code - - message + AuditLogTypes: + description: The type of the audit log + type: string + enum: + - user_created + - password_set_succeeded + - password_set_failed + - password_login_succeeded + - password_login_failed + - passcode_login_init_succeeded + - passcode_login_init_failed + - passcode_login_final_succeeded + - passcode_login_final_failed + - webauthn_registration_init_succeeded + - webauthn_registration_init_failed + - webauthn_registration_final_succeeded + - webauthn_registration_final_failed + - webauthn_authentication_init_succeeded + - webauthn_authentication_init_failed + - webauthn_authentication_final_succeeded + - webauthn_authentication_final_failed + - thirdparty_signup_succeeded + - thirdparty_signin_succeeded + headers: + X-Total-Count: + schema: + type: string + description: The total count of the requested resource considering query parameter + example: 1234 + Link: + schema: + type: string + description: Web Linking as described in RFC5988 + example: ; rel="first",; rel="last",; rel="next",; rel="prev"