0
Fork 0
mirror of https://github.com/logto-io/logto.git synced 2024-12-16 20:26:19 -05:00

refactor(core): improve swagger auth description (#6367)

This commit is contained in:
Gao Sun 2024-07-31 17:22:07 +08:00 committed by GitHub
parent f8185a651b
commit 84f7e13a2b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 30 additions and 17 deletions

View file

@ -0,0 +1,7 @@
---
"@logto/core": patch
---
use native OpenAPI OAuth 2 security schema
The built-in OpenAPI OAuth 2 security schema is now used instead of the custom HTTP header-based security schema. This change improves compatibility with OpenAPI tools and libraries that support OAuth 2.

View file

@ -1,4 +1,4 @@
export const managementApiDescription = `Logto Management API is a comprehensive set of REST APIs that gives you the full control over Logto to suit your product needs and tech stack. To see the full guide on Management API interactions, visit [Interact with Management API](https://docs.logto.io/docs/recipes/interact-with-management-api/). export const managementApiAuthDescription = `Logto Management API is a comprehensive set of REST APIs that gives you the full control over Logto to suit your product needs and tech stack. To see the full guide on Management API interactions, visit [Interact with Management API](https://docs.logto.io/docs/recipes/interact-with-management-api/).
### Get started ### Get started
@ -21,13 +21,13 @@ For Logto Cloud users, the base URL is your Logto endpoint, i.e. \`https://[tena
The request should follow the OAuth 2.0 [client credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type. Here is a non-normative example of how to fetch an access token: The request should follow the OAuth 2.0 [client credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type. Here is a non-normative example of how to fetch an access token:
\`\`\`bash \`\`\`bash
curl --location \ curl --location \\
--request POST 'https://[tenant-id].logto.app/oidc/token' \ --request POST 'https://[tenant-id].logto.app/oidc/token' \\
--header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'grant_type=client_credentials' \\
--data-urlencode 'client_id=[app-id]' \ --data-urlencode 'client_id=[app-id]' \\
--data-urlencode 'client_secret=[app-secret]' \ --data-urlencode 'client_secret=[app-secret]' \\
--data-urlencode 'resource=https://[tenant-id].logto.app/api' \ --data-urlencode 'resource=https://[tenant-id].logto.app/api' \\
--data-urlencode 'scope=all' --data-urlencode 'scope=all'
\`\`\` \`\`\`
@ -51,8 +51,8 @@ Once you have the access token, you can use it to authenticate your requests to
Here is an example of how to list the first page of users in your Logto tenant: Here is an example of how to list the first page of users in your Logto tenant:
\`\`\`bash \`\`\`bash
curl --location \ curl --location \\
--request GET 'https://[tenant-id].logto.app/api/users' \ --request GET 'https://[tenant-id].logto.app/api/users' \\
--header 'Authorization: Bearer eyJhbG...2g' --header 'Authorization: Bearer eyJhbG...2g'
\`\`\` \`\`\`

View file

@ -21,7 +21,7 @@ import { translationSchemas, zodTypeToSwagger } from '#src/utils/zod.js';
import type { AnonymousRouter } from '../types.js'; import type { AnonymousRouter } from '../types.js';
import { managementApiDescription } from './consts.js'; import { managementApiAuthDescription } from './consts.js';
import { import {
buildTag, buildTag,
devFeatureTag, devFeatureTag,
@ -270,14 +270,20 @@ export default function swaggerRoutes<T extends AnonymousRouter, R extends Route
version: 'Cloud', version: 'Cloud',
}, },
paths: Object.fromEntries(pathMap), paths: Object.fromEntries(pathMap),
security: [{ ManagementApi: [] }], security: [{ OAuth2: ['all'] }],
components: { components: {
securitySchemes: { securitySchemes: {
ManagementApi: { OAuth2: {
type: 'http', type: 'oauth2',
scheme: 'bearer', description: managementApiAuthDescription,
bearerFormat: 'JWT', flows: {
description: managementApiDescription, clientCredentials: {
tokenUrl: '/oidc/token',
scopes: {
all: 'All scopes',
},
},
},
}, },
}, },
schemas: translationSchemas, schemas: translationSchemas,