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

.changeset/cyan-bottles-call.md

@@ -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.

packages/core/src/routes/swagger/consts.ts

@@ -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
 
@@ -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:
 
 \`\`\`bash
-curl --location \
-  --request POST 'https://[tenant-id].logto.app/oidc/token' \
-  --header 'Content-Type: application/x-www-form-urlencoded' \
-  --data-urlencode 'grant_type=client_credentials' \
-  --data-urlencode 'client_id=[app-id]' \
-  --data-urlencode 'client_secret=[app-secret]' \
-  --data-urlencode 'resource=https://[tenant-id].logto.app/api' \
+curl --location \\
+  --request POST 'https://[tenant-id].logto.app/oidc/token' \\
+  --header 'Content-Type: application/x-www-form-urlencoded' \\
+  --data-urlencode 'grant_type=client_credentials' \\
+  --data-urlencode 'client_id=[app-id]' \\
+  --data-urlencode 'client_secret=[app-secret]' \\
+  --data-urlencode 'resource=https://[tenant-id].logto.app/api' \\
   --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:
 
 \`\`\`bash
-curl --location \
-  --request GET 'https://[tenant-id].logto.app/api/users' \
+curl --location \\
+  --request GET 'https://[tenant-id].logto.app/api/users' \\
   --header 'Authorization: Bearer eyJhbG...2g'
 \`\`\`
 

packages/core/src/routes/swagger/index.ts

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