feat: add swagger operationId (#3122)

* feat: add swagger operationId * chore(docs): update documents for swagger
midwayjs · Aug 1, 2023 · 4db39a6 · 4db39a6
1 parent a196b53
commit 4db39a6
Show file tree

Hide file tree

Showing 6 changed files with 70 additions and 12 deletions.
diff --git a/packages/swagger/src/interfaces/index.ts b/packages/swagger/src/interfaces/index.ts
@@ -3,6 +3,8 @@
  * @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc0/versions/3.0.md
  */
 
+import type { RouterOption } from '@midwayjs/core';
+
 export interface OpenAPIObject {
   openapi: string;
   info: InfoObject;
@@ -412,4 +414,14 @@ export interface SwaggerOptions {
     useUnsafeMarkdown?: boolean;
     tryItOutEnabled?: boolean;
   };
+  documentOptions?: {
+    /**
+     * 自定义 operationIdFactory，用于生成 operationId
+     * @default () => controllerKey_webRouter.methodKey
+     */
+    operationIdFactory?: (
+      controllerKey: string,
+      webRouter: RouterOption
+    ) => string;
+  };
 }
diff --git a/packages/swagger/src/swaggerExplorer.ts b/packages/swagger/src/swaggerExplorer.ts
@@ -38,6 +38,10 @@ export class SwaggerExplorer {
   private swaggerConfig: SwaggerOptions;
 
   private documentBuilder = new DocumentBuilder();
+  private operationIdFactory = (
+    controllerKey: string,
+    webRouter: RouterOption
+  ) => `${controllerKey.toLowerCase()}_${webRouter.method.toLocaleLowerCase()}`;
 
   @Init()
   async init() {
@@ -92,6 +96,12 @@ export class SwaggerExplorer {
         this.documentBuilder.addTag(t.name, t.description, t.externalDocs);
       }
     }
+
+    if (this.swaggerConfig?.documentOptions?.operationIdFactory) {
+      this.operationIdFactory =
+        this.swaggerConfig.documentOptions.operationIdFactory;
+    }
+
     // 设置 auth 类型
     if (Array.isArray(this.swaggerConfig?.auth)) {
       for (const a of this.swaggerConfig?.auth) {
@@ -292,7 +302,7 @@ export class SwaggerExplorer {
         operMeta?.metadata?.description,
         webRouter.description
       ),
-      // operationId: `${webRouter.requestMethod}_${(operMeta?.metadata?.operationId || webRouter.method)}`,
+      operationId: this.getOperationId(target.name, webRouter),
       tags: operMeta?.metadata?.tags || [],
     };
     /**
@@ -503,6 +513,10 @@ export class SwaggerExplorer {
     paths[url] = opts;
   }
 
+  getOperationId(controllerKey: string, webRouter: RouterOption) {
+    return this.operationIdFactory(controllerKey, webRouter);
+  }
+
   private expandSchemaRef(p: any, name?: string) {
     let schemaName = name;
     if (p.schema['$ref']) {

diff --git a/packages/swagger/test/__snapshots__/index.test.ts.snap b/packages/swagger/test/__snapshots__/index.test.ts.snap
@@ -67,6 +67,7 @@ exports[`/test/index.test.ts should fix issue1976 1`] = `
   "paths": {
     "/cats/login": {
       "post": {
+        "operationId": "usercontroller_login",
         "parameters": [],
         "requestBody": {
           "content": {
@@ -92,6 +93,7 @@ exports[`/test/index.test.ts should fix issue1976 1`] = `
     },
     "/cats/smsLogin": {
       "post": {
+        "operationId": "usercontroller_smslogin",
         "parameters": [],
         "requestBody": {
           "content": {
@@ -170,6 +172,7 @@ exports[`/test/index.test.ts should fix issue2603 1`] = `
   "paths": {
     "/api/get_role": {
       "get": {
+        "operationId": "apicontroller_getrole",
         "parameters": [],
         "responses": {
           "default": {
@@ -190,6 +193,7 @@ exports[`/test/index.test.ts should fix issue2603 1`] = `
     },
     "/api/get_user": {
       "get": {
+        "operationId": "apicontroller_getuser",
         "parameters": [
           {
             "in": "query",
@@ -397,6 +401,7 @@ exports[`/test/index.test.ts test swagger should get swagger json 5`] = `
 exports[`/test/index.test.ts test swagger should get swagger json 6`] = `
 {
   "get": {
+    "operationId": "cats_findone",
     "parameters": [
       {
         "in": "header",
@@ -486,6 +491,7 @@ exports[`/test/index.test.ts test swagger should get swagger json 6`] = `
     },
   },
   "post": {
+    "operationId": "cats_create",
     "parameters": [
       {
         "in": "header",

diff --git a/packages/swagger/test/__snapshots__/parser.test.ts.snap b/packages/swagger/test/__snapshots__/parser.test.ts.snap
@@ -58,6 +58,7 @@ exports[`/test/parser.test.ts should fix issue#2286 with array example 1`] = `
     "/api/update_user": {
       "post": {
         "description": undefined,
+        "operationId": "catcontroller_updateuser",
         "parameters": [],
         "responses": {
           "200": {
@@ -299,6 +300,7 @@ exports[`/test/parser.test.ts should test ref path generate 1`] = `
     "/api/update_user": {
       "post": {
         "description": undefined,
+        "operationId": "apicontroller_updateuser",
         "parameters": [],
         "responses": {
           "200": {
@@ -358,6 +360,7 @@ exports[`/test/parser.test.ts should test simple case with example 1`] = `
     "/api/update_user": {
       "post": {
         "description": undefined,
+        "operationId": "catcontroller_updateuser",
         "parameters": [],
         "responses": {
           "200": {

diff --git a/packages/swagger/test/index.test.ts b/packages/swagger/test/index.test.ts
@@ -3,13 +3,26 @@ import * as koa from '@midwayjs/koa';
 import { join } from 'path';
 
 describe('/test/index.test.ts', () => {
-
+  
   describe('test swagger', () => {
-
+    
     let app;
     beforeAll(async () => {
       try {
-        app = await createApp(join(__dirname, 'fixtures/cats'), {}, koa);
+        app = await createApp(
+          join(__dirname, 'fixtures/cats'),
+          {
+            globalConfig: {
+              swagger: {
+                documentOptions: {
+                  operationIdFactory: (c, r) =>
+                    `${c.replace('Controller', '')}_${r.method}`.toLowerCase(),
+                },
+              },
+            },
+          },
+          koa
+        );
       } catch (e) {
         console.log(e);
         console.log('beforeAll: ' +  e.stack);

diff --git a/site/docs/extensions/swagger.md b/site/docs/extensions/swagger.md
@@ -3,13 +3,13 @@
 
 相关信息：
 
-| 描述              |      |
-| ----------------- | ---- |
-| 可用于标准项目    | ✅    |
-| 可用于 Serverless | ❌    |
-| 可用于一体化      | ❌    |
-| 包含独立主框架    | ❌    |
-| 包含独立日志      | ❌    |
+| 描述              |     |
+| ----------------- | --- |
+| 可用于标准项目    | ✅   |
+| 可用于 Serverless | ❌   |
+| 可用于一体化      | ❌   |
+| 包含独立主框架    | ❌   |
+| 包含独立日志      | ❌   |
 
 
 
@@ -970,7 +970,17 @@ export interface SwaggerOptions {
     useUnsafeMarkdown?: boolean;
     tryItOutEnabled?: boolean;
   };
-}
+
+  documentOptions?: {
+    /**
+     * 自定义 operationIdFactory，用于生成 operationId
+     * @default () => controllerKey_webRouter.methodKey
+     */
+    operationIdFactory?: (
+      controllerKey: string,
+      webRouter: RouterOption
+    ) => string;
+  };}
 /**
  * 继承自 https://swagger.io/specification/#security-scheme-object
  */