From ad60de8f24e4efedfbd33ff362173d2c0e847dc1 Mon Sep 17 00:00:00 2001 From: Xiao Yijun Date: Sun, 3 Dec 2023 00:05:57 +0800 Subject: [PATCH] chore(core): add logto-config api doc descriptions (#5033) * chore(core): add logto-config api doc descriptions * chore(core): polish docs --------- Co-authored-by: Gao Sun --- .../core/src/routes/logto-config.openapi.json | 109 ++++++++++++++++++ packages/core/src/routes/logto-config.ts | 17 +-- 2 files changed, 110 insertions(+), 16 deletions(-) create mode 100644 packages/core/src/routes/logto-config.openapi.json diff --git a/packages/core/src/routes/logto-config.openapi.json b/packages/core/src/routes/logto-config.openapi.json new file mode 100644 index 000000000..06cf1e4cd --- /dev/null +++ b/packages/core/src/routes/logto-config.openapi.json @@ -0,0 +1,109 @@ +{ + "tags": [ + { + "name": "Configs", + "description": "Endpoints for managing Logto global configurations for the tenant." + } + ], + "paths": { + "/api/configs/admin-console": { + "get": { + "summary": "Get admin console config", + "description": "Get the global configuration object for Logto Console.", + "responses": { + "200": { + "description": "The configuration object." + }, + "404": { + "description": "Configuration not found." + } + } + }, + "patch": { + "summary": "Update admin console config", + "description": "Update the global configuration object for Logto Console. This method performs a partial update.", + "responses": { + "200": { + "description": "The updated configuration object." + }, + "404": { + "description": "Configuration not found." + } + } + } + }, + "/api/configs/oidc/{keyType}": { + "get": { + "summary": "Get OIDC keys", + "description": "Get OIDC keys by key type. The actual key will be redacted from the result.", + "parameters": [ + { + "in": "path", + "name": "keyType", + "description": "Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead." + } + ], + "responses": { + "200": { + "description": "An array of OIDC keys for the given key type." + } + } + } + }, + "/api/configs/oidc/{keyType}/{keyId}": { + "delete": { + "summary": "Delete OIDC key", + "description": "Delete an OIDC key by key type and key ID.", + "parameters": [ + { + "in": "path", + "name": "keyType", + "description": "Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead." + } + ], + "responses": { + "204": { + "description": "The key was deleted successfully." + }, + "404": { + "description": "The key was not found." + }, + "422": { + "description": "At least one key must be kept." + } + } + } + }, + "/api/configs/oidc/{keyType}/rotate": { + "post": { + "summary": "Rotate OIDC keys", + "description": "A new key will be generated and prepend to the list of keys.\n\nOnly two recent keys will be kept. The oldest key will be automatically removed if there are more than two keys.", + "parameters": [ + { + "in": "path", + "name": "keyType", + "description": "Private keys are used to sign OIDC JWTs. Cookie keys are used to sign OIDC cookies. For clients, they do not need to know private keys to verify OIDC JWTs; they can use public keys from the JWKS endpoint instead." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "signingKeyAlgorithm": { + "description": "The signing key algorithm the new generated private key is using.\n\nOnly applicable when `keyType` is `private-keys`." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "An array of OIDC keys after rotation." + } + } + } + } + } +} diff --git a/packages/core/src/routes/logto-config.ts b/packages/core/src/routes/logto-config.ts index dc2be7bb2..dcdbd3a08 100644 --- a/packages/core/src/routes/logto-config.ts +++ b/packages/core/src/routes/logto-config.ts @@ -90,10 +90,6 @@ export default function logtoConfigRoutes( } ); - /** - * Get Logto OIDC private keys from database. The actual key will be redacted from the result. - * @param keyType Logto OIDC private key type. Values are either `private-keys` or `cookie-keys`. - */ router.get( '/configs/oidc/:keyType', koaGuard({ @@ -101,7 +97,7 @@ export default function logtoConfigRoutes( keyType: z.nativeEnum(LogtoOidcConfigKeyType), }), response: z.array(oidcConfigKeysResponseGuard), - status: [200, 404], + status: [200], }), async (ctx, next) => { const { keyType } = ctx.guard.params; @@ -115,11 +111,6 @@ export default function logtoConfigRoutes( } ); - /** - * Delete a Logto OIDC private key from database. - * @param keyType Logto OIDC key type. Values are either `oidc.privateKeys` or `oidc.cookieKeys`. - * @param keyId The ID of the private key to be deleted. - */ router.delete( '/configs/oidc/:keyType/:keyId', koaGuard({ @@ -154,12 +145,6 @@ export default function logtoConfigRoutes( } ); - /** - * Rotate Logto OIDC private keys. A new key will be generated and added to the list of private keys. - * Only keep the last 2 recent keys. The oldest key will be automatically removed if the list exceeds 2 keys. - * @param configKey Logto OIDC key type. Values are either `oidc.privateKeys` or `oidc.cookieKeys`. - * @param signingKeyAlgorithm The signing key algorithm the new generated private key is using. Values are either `EC` or `RSA`. Only applicable to `oidc.privateKeys`. Defaults to `EC`. - */ router.post( '/configs/oidc/:keyType/rotate', koaGuard({