Merge pull request #10 from wangweianger/master

feat: 1.tags字段注释优先 2.operationId字段规则更新为 controller+方法名+method+path route

Author: wangweianger

openapi/openapiv3.json

@@ -1 +1 @@
-{"openapi":"3.0.3","info":{"title":"routing-controllers-to-openapi","description":"Buildtime OpenAPI v3 spec generation for routing-controllers","version":"1.0.0"},"tags":[{"name":"ExampleController","description":"测试案例controller"}],"paths":{"/example/test/{id}/{name}":{"post":{"tags":["ExampleController"],"summary":"do something","description":"ExampleController.getTest 测试案例controller ","operationId":"ExampleController.post.getTest.zJtCBwDnjR","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","description":"code返回码"},"message":{"type":"string","description":"返回信息"}},"required":["code","message"],"additionalProperties":false}}}}},"parameters":[{"name":"id","in":"path","description":"@Param, 类型：string","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","description":"姓名 (@Param, 类型：string)","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"params":{"type":"object","properties":{"name":{"type":"string"},"age":{"$ref":"#/components/schemas/Aaa"}},"required":["name","age"],"description":"@BodyParam"}},"required":["params"]}}}}}}},"components":{"schemas":{"Aaa":{"type":"object","properties":{"code":{"type":"string","enum":["a","b"]}},"required":["code"],"additionalProperties":false}}}}
+{"openapi":"3.0.3","info":{"title":"routing-controllers-to-openapi","description":"Buildtime OpenAPI v3 spec generation for routing-controllers","version":"1.0.0"},"tags":[{"name":"测试案例controller","description":"ExampleController"}],"paths":{"/example/test/{id}/{name}":{"post":{"tags":["测试案例controller"],"summary":"do something","description":"ExampleController.getTest 测试案例controller ","operationId":"ExampleController_getTest_post_example_test_{id}_{name}","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","description":"code返回码"},"message":{"type":"string","description":"返回信息"}},"required":["code","message"],"additionalProperties":false}}}}},"parameters":[{"name":"id","in":"path","description":"@Param, 类型：string","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","description":"姓名 (@Param, 类型：string)","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"params":{"type":"object","properties":{"name":{"type":"string"},"age":{"$ref":"#/components/schemas/Aaa"}},"required":["name","age"],"description":"@BodyParam"}},"required":["params"]}}}}}}},"components":{"schemas":{"Aaa":{"type":"object","properties":{"code":{"type":"string","enum":["a","b"]}},"required":["code"],"additionalProperties":false}}}}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "routing-controllers-to-openapi",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "main": "./dist/index.js",
   "typings": "dist/index.d.ts",
   "repository": "https://github.com/yunke-yunfly/routing-controllers-to-openapi",
@@ -83,4 +83,4 @@
     "glob": "^7.2.0",
     "lodash": "^4.17.21"
   }
-}
+}

src/gen-openapi.ts

@@ -1,6 +1,5 @@
 import * as path from 'path';
 import * as _ from 'lodash';
-import { randomString } from './util';
 // types
 import type {
   AnyOpt,
@@ -111,13 +110,14 @@ export function genTags(paths: TraverseAstConfig[]): Openapiv3Tags[] {
   const cache: Record<string, number> = {};
 
   return paths.reduce((prev: Openapiv3Tags[], path: TraverseAstConfig) => {
-    if (!cache[path.className] && path.className) {
-      cache[path.className] = 1;
+    const tag = path.description || path.className;
+    if (!cache[tag] && tag) {
+      cache[tag] = 1;
       return [
         ...prev,
         {
-          name: path.className,
-          description: path.description,
+          name: tag,
+          description: path.className,
         },
       ];
     }
@@ -154,11 +154,12 @@ export function genPaths(
       // 处理路由
       const res = (itemPath.paths || []).reduce((childPrevPath: AnyOpt, childItemPath: AnyOpt) => {
         const method = (childItemPath.method || '').toLowerCase();
+        const tag = next.description || next.className;
         const methodJson: MethodConfig = {
-          tags: [next.className],
+          tags: [tag],
           summary: itemPath.description || childItemPath.operationId || '',
           description: itemPath.description_ || `${next.className}.${childItemPath.operationId} ${next.description} `,
-          operationId: `${next.className}.${method}.${childItemPath.operationId}.${randomString(10)}`,
+          operationId: `${next.className}_${childItemPath.operationId}_${method}${childItemPath.routerPath.replace(/\//g, '_')}`,
           responses,
         };
         if (parameters.length) methodJson.parameters = parameters;

test/SimpleController.ts

@@ -19,7 +19,7 @@ export default class {
     @QueryParam('simple3') simple3: boolean,
     @QueryParam('simple4') simple4: any,
     @QueryParam('simple5', { required: true }) simple5: never,
-    @QueryParam('simple6') simple6: {name: string},
+    @QueryParam('simple6') simple6: { name: string },
     @Param('id', { required: true }) id: number,
     @UseMetadata() metadata: any,
   ): Promise<{ name: string }> {
@@ -44,6 +44,7 @@ export default class {
 
   /**
    * do something
+   * @description 测试函数备注信息
    *
    * @param {string} orgcode 租户号
    * @param {string} name 姓名