From 84f7e13a2b9213a3b897e40a0654ec0034680d9a Mon Sep 17 00:00:00 2001
From: Gao Sun <gao@silverhand.io>
Date: Wed, 31 Jul 2024 17:22:07 +0800
Subject: [PATCH] refactor(core): improve swagger auth description (#6367)

---
 .changeset/cyan-bottles-call.md            |  7 +++++++
 packages/core/src/routes/swagger/consts.ts | 20 ++++++++++----------
 packages/core/src/routes/swagger/index.ts  | 20 +++++++++++++-------
 3 files changed, 30 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/cyan-bottles-call.md

diff --git a/.changeset/cyan-bottles-call.md b/.changeset/cyan-bottles-call.md
new file mode 100644
index 000000000..65889393d
--- /dev/null
+++ b/.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.
diff --git a/packages/core/src/routes/swagger/consts.ts b/packages/core/src/routes/swagger/consts.ts
index 9ff296013..8b08f1307 100644
--- a/packages/core/src/routes/swagger/consts.ts
+++ b/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'
 \`\`\`
 
diff --git a/packages/core/src/routes/swagger/index.ts b/packages/core/src/routes/swagger/index.ts
index 0ce1172bb..1771c06d8 100644
--- a/packages/core/src/routes/swagger/index.ts
+++ b/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,