@midwayjs/swagger 3.17.1 → 3.17.3

package/dist/config/config.default.js

@@ -13,5 +13,6 @@ exports.swagger = {
         ? render_1.renderSwaggerUIDist
         : render_1.renderSwaggerUIRemote,
     swaggerUIRenderOptions: {},
+    isGenerateTagForController: true,
 };
 //# sourceMappingURL=config.default.js.map

package/dist/documentBuilder.js

@@ -95,6 +95,19 @@ class DocumentBuilder {
                 externalDocs,
             });
         }
+        else {
+            // update description and externalDocs
+            tags.forEach(tag => {
+                if (tag.name === name) {
+                    if (description) {
+                        tag.description = description;
+                    }
+                    if (externalDocs) {
+                        tag.externalDocs = externalDocs;
+                    }
+                }
+            });
+        }
         this.document.tags = tags;
         return this;
     }

package/dist/interfaces/index.d.ts

@@ -373,6 +373,10 @@ export interface SwaggerOptions {
      * 自定义路由过滤器
      */
     routerFilter?: (url: string, options: RouterOption) => boolean;
+    /**
+     * Weather to generate the Tag for controller
+     */
+    isGenerateTagForController?: boolean;
 }
 export interface MixDecoratorMetadata {
     key: string;

package/dist/swaggerExplorer.d.ts

@@ -1,5 +1,6 @@
 import { RouterOption } from '@midwayjs/core';
 import { Type } from './interfaces';
+import { DocumentBuilder } from './documentBuilder';
 export declare class SwaggerExplorer {
     private swaggerConfig;
     private documentBuilder;
@@ -8,18 +9,13 @@ export declare class SwaggerExplorer {
     addGlobalPrefix(globalPrefix: string): void;
     scanApp(): void;
     getData(): Omit<import("./interfaces").OpenAPIObject, "paths">;
+    getDocumentBuilder(): DocumentBuilder;
     protected generatePath(target: Type): void;
     /**
      * 构造 router 提取方法
      */
     private generateRouteMethod;
     getOperationId(controllerKey: string, webRouter: RouterOption): string;
-    /**
-     * 提取参数
-     * @param params
-     * @param p
-     */
-    protected parseFromParamsToP(paramMeta: any, p: any): void;
     /**
      * 解析 ApiExtraModel
      * @param clzz

package/dist/swaggerExplorer.js

@@ -96,13 +96,18 @@ let SwaggerExplorer = class SwaggerExplorer {
     getData() {
         return this.documentBuilder.build();
     }
+    getDocumentBuilder() {
+        return this.documentBuilder;
+    }
     generatePath(target) {
+        var _a;
         // 获取控制器元数据
         const excludeClassMeta = (0, core_1.getClassMetadata)(constants_1.DECORATORS.API_EXCLUDE_CONTROLLER, target);
         if (excludeClassMeta && excludeClassMeta.disable) {
             // 如果存在需要排除的控制器，则直接返回
             return;
         }
+        const isGenerateTagForController = (_a = this.swaggerConfig.isGenerateTagForController) !== null && _a !== void 0 ? _a : true;
         // 解析额外的模型
         this.parseExtraModel(target);
         const metaForClass = (0, core_1.getClassMetadata)(constants_1.DECORATORS_CLASS_METADATA, target) || [];
@@ -118,33 +123,35 @@ let SwaggerExplorer = class SwaggerExplorer {
         const controllerTags = [];
         // 如果存在标签，则将其添加到文档构建器中
         if (tags.length > 0) {
-            for (const t of tags) {
-                // 这里 metadata => string[]
-                strTags = strTags.concat(t.metadata);
-                controllerTags.push(Array.isArray(t.metadata) ? [t.metadata] : t.metadata);
-                // this.documentBuilder.addTag(t.metadata);
-            }
+            strTags = parseTags(tags);
+            strTags.forEach(tag => {
+                addTag(tag, controllerTags);
+            });
         }
         else {
-            // 如果不存在标签，则根据控制器选项生成标签
-            const tag = { name: '', description: '' };
-            if (prefix !== '/') {
-                tag.name =
-                    (controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.tagName) ||
-                        (/^\//.test(prefix) ? prefix.split('/')[1] : prefix);
-                tag.description =
-                    (controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.description) || tag.name;
+            if (isGenerateTagForController) {
+                // 如果不存在标签，则根据控制器选项生成标签
+                const tag = { name: '', description: '' };
+                if (prefix !== '/') {
+                    tag.name =
+                        (controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.tagName) ||
+                            (/^\//.test(prefix) ? prefix.split('/')[1] : prefix);
+                    tag.description =
+                        (controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.description) || tag.name;
+                }
+                else {
+                    tag.name = controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.tagName;
+                    tag.description =
+                        (controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.description) || tag.name;
+                }
+                // 如果标签名存在，则将其添加到文档构建器中
+                if (tag.name) {
+                    strTags.push(tag.name);
+                    addTag([tag.name, tag.description], controllerTags);
+                }
             }
             else {
-                tag.name = controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.tagName;
-                tag.description =
-                    (controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.description) || tag.name;
-            }
-            // 如果标签名存在，则将其添加到文档构建器中
-            if (tag.name) {
-                strTags.push(tag.name);
-                controllerTags.push([tag.name, tag.description]);
-                // this.documentBuilder.addTag(tag.name, tag.description);
+                // 否则不添加标签
             }
         }
         // 获取路由信息
@@ -198,6 +205,12 @@ let SwaggerExplorer = class SwaggerExplorer {
                 if (paths[url][webRouter.requestMethod].tags.length === 0) {
                     paths[url][webRouter.requestMethod].tags = strTags;
                 }
+                else {
+                    // 如果 tags 不在全局中，则添加
+                    paths[url][webRouter.requestMethod].tags.forEach(tag => {
+                        addTag(tag, controllerTags);
+                    });
+                }
                 // 过滤出扩展信息
                 const exts = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_EXTENSION &&
                     item.propertyName === webRouter.method);
@@ -242,9 +255,12 @@ let SwaggerExplorer = class SwaggerExplorer {
      * 构造 router 提取方法
      */
     generateRouteMethod(url, webRouter, paths, metaForMethods, routerArgs, headers, target) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
         const operMeta = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_OPERATION &&
             item.propertyName === webRouter.method)[0];
+        const routerTagsMeta = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_TAGS &&
+            item.propertyName === webRouter.method);
+        const routerTags = parseTags(routerTagsMeta);
         let opts = paths[url];
         if (!opts) {
             opts = {};
@@ -255,11 +271,11 @@ let SwaggerExplorer = class SwaggerExplorer {
             description: getNotEmptyValue((_b = operMeta === null || operMeta === void 0 ? void 0 : operMeta.metadata) === null || _b === void 0 ? void 0 : _b.description, webRouter.description),
             operationId: ((_c = operMeta === null || operMeta === void 0 ? void 0 : operMeta.metadata) === null || _c === void 0 ? void 0 : _c.operationId) ||
                 this.getOperationId(target.name, webRouter),
-            tags: ((_d = operMeta === null || operMeta === void 0 ? void 0 : operMeta.metadata) === null || _d === void 0 ? void 0 : _d.tags) || [],
+            tags: routerTags.length ? routerTags : (_e = (_d = operMeta === null || operMeta === void 0 ? void 0 : operMeta.metadata) === null || _d === void 0 ? void 0 : _d.tags) !== null && _e !== void 0 ? _e : [],
         };
-        if (((_e = operMeta === null || operMeta === void 0 ? void 0 : operMeta.metadata) === null || _e === void 0 ? void 0 : _e.deprecated) != null) {
+        if (((_f = operMeta === null || operMeta === void 0 ? void 0 : operMeta.metadata) === null || _f === void 0 ? void 0 : _f.deprecated) != null) {
             opts[webRouter.requestMethod].deprecated =
-                !!((_f = operMeta === null || operMeta === void 0 ? void 0 : operMeta.metadata) === null || _f === void 0 ? void 0 : _f.deprecated);
+                !!((_g = operMeta === null || operMeta === void 0 ? void 0 : operMeta.metadata) === null || _g === void 0 ? void 0 : _g.deprecated);
         }
         /**
          * [{"key":"web:router_param","parameterIndex":1,"propertyName":"create","metadata":{"type":2}},
@@ -283,7 +299,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                     param.metadata.schema['type'] = param.metadata.type;
                     delete param.metadata.type;
                 }
-                if (param.metadata.isArray !== undefined) {
+                if (param.metadata.isArray) {
                     param.metadata.schema['items'] = {
                         type: param.metadata.schema['type'],
                     };
@@ -307,9 +323,9 @@ let SwaggerExplorer = class SwaggerExplorer {
                 parameters.push(p);
             }
             else if (p.in === 'body') {
-                p.content = (_g = p.content) !== null && _g !== void 0 ? _g : {};
+                p.content = (_h = p.content) !== null && _h !== void 0 ? _h : {};
                 if (Object.keys(p.content).length === 0) {
-                    p.content[p.contentType || 'application/json'] = (_h = p.content[p.contentType || 'application/json']) !== null && _h !== void 0 ? _h : {
+                    p.content[p.contentType || 'application/json'] = (_j = p.content[p.contentType || 'application/json']) !== null && _j !== void 0 ? _j : {
                         schema: p.schema,
                     };
                 }
@@ -319,20 +335,20 @@ let SwaggerExplorer = class SwaggerExplorer {
                 }
                 // if requestBody is already set, skip
                 opts[webRouter.requestMethod].requestBody =
-                    (_j = opts[webRouter.requestMethod].requestBody) !== null && _j !== void 0 ? _j : {};
+                    (_k = opts[webRouter.requestMethod].requestBody) !== null && _k !== void 0 ? _k : {};
                 opts[webRouter.requestMethod].requestBody.description =
-                    (_k = opts[webRouter.requestMethod].requestBody.description) !== null && _k !== void 0 ? _k : p.description;
+                    (_l = opts[webRouter.requestMethod].requestBody.description) !== null && _l !== void 0 ? _l : p.description;
                 opts[webRouter.requestMethod].requestBody.content =
-                    (_l = opts[webRouter.requestMethod].requestBody.content) !== null && _l !== void 0 ? _l : p.content;
+                    (_m = opts[webRouter.requestMethod].requestBody.content) !== null && _m !== void 0 ? _m : p.content;
                 opts[webRouter.requestMethod].requestBody.required =
-                    (_m = opts[webRouter.requestMethod].requestBody.required) !== null && _m !== void 0 ? _m : p.required;
+                    (_o = opts[webRouter.requestMethod].requestBody.required) !== null && _o !== void 0 ? _o : p.required;
             }
         }
         for (const arg of args) {
             const currentType = types[arg.parameterIndex];
             const p = {
-                name: (_o = arg === null || arg === void 0 ? void 0 : arg.metadata) === null || _o === void 0 ? void 0 : _o.propertyData,
-                in: convertTypeToString((_p = arg.metadata) === null || _p === void 0 ? void 0 : _p.type),
+                name: (_p = arg === null || arg === void 0 ? void 0 : arg.metadata) === null || _p === void 0 ? void 0 : _p.propertyData,
+                in: convertTypeToString((_q = arg.metadata) === null || _q === void 0 ? void 0 : _q.type),
                 required: false,
             };
             const existsParam = parameters.find(item => {
@@ -357,12 +373,13 @@ let SwaggerExplorer = class SwaggerExplorer {
                     // 如果@Query()装饰的 是一个对象，则把该对象的子属性作为多个@Query参数
                     const schema = this.documentBuilder.getSchema(currentType.name);
                     Object.keys(schema.properties).forEach(pName => {
-                        var _a;
+                        var _a, _b;
                         const pp = {
                             name: pName,
                             in: p.in,
+                            description: (_a = schema.properties[pName]) === null || _a === void 0 ? void 0 : _a.description,
                             schema: schema.properties[pName],
-                            required: ((_a = schema.required) === null || _a === void 0 ? void 0 : _a.includes(pName)) || false,
+                            required: ((_b = schema.required) === null || _b === void 0 ? void 0 : _b.includes(pName)) || false,
                         };
                         parameters.push(pp);
                     });
@@ -373,7 +390,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                         continue;
                     }
                     p.schema = {
-                        type: convertSchemaType((_q = currentType === null || currentType === void 0 ? void 0 : currentType.name) !== null && _q !== void 0 ? _q : currentType),
+                        type: convertSchemaType((_r = currentType === null || currentType === void 0 ? void 0 : currentType.name) !== null && _r !== void 0 ? _r : currentType),
                     };
                 }
             }
@@ -386,7 +403,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                     continue;
                 }
                 // 这里兼容一下 @File()、@Files()、@Fields() 装饰器
-                if (((_r = arg.metadata) === null || _r === void 0 ? void 0 : _r.type) === core_1.RouteParamTypes.FILESSTREAM) {
+                if (((_s = arg.metadata) === null || _s === void 0 ? void 0 : _s.type) === core_1.RouteParamTypes.FILESSTREAM) {
                     p.content = {};
                     p.content[_1.BodyContentType.Multipart] = {
                         schema: {
@@ -404,7 +421,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                         },
                     };
                 }
-                else if (((_s = arg.metadata) === null || _s === void 0 ? void 0 : _s.type) === core_1.RouteParamTypes.FILESTREAM) {
+                else if (((_t = arg.metadata) === null || _t === void 0 ? void 0 : _t.type) === core_1.RouteParamTypes.FILESTREAM) {
                     p.content = {};
                     p.content[_1.BodyContentType.Multipart] = {
                         schema: {
@@ -434,7 +451,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                         p.content = {
                             'text/plain': {
                                 schema: {
-                                    type: convertSchemaType((_t = currentType === null || currentType === void 0 ? void 0 : currentType.name) !== null && _t !== void 0 ? _t : currentType),
+                                    type: convertSchemaType((_u = currentType === null || currentType === void 0 ? void 0 : currentType.name) !== null && _u !== void 0 ? _u : currentType),
                                 },
                             },
                         };
@@ -526,96 +543,6 @@ let SwaggerExplorer = class SwaggerExplorer {
     getOperationId(controllerKey, webRouter) {
         return this.operationIdFactory(controllerKey, webRouter);
     }
-    /**
-     * 提取参数
-     * @param params
-     * @param p
-     */
-    parseFromParamsToP(paramMeta, p) {
-        var _a, _b, _c;
-        if (paramMeta) {
-            const param = paramMeta.metadata;
-            if (param) {
-                p.description = param.description;
-                if (!p.name && param.name) {
-                    p.name = param.name;
-                }
-                if (param.in === 'query') {
-                    p.allowEmptyValue = param.allowEmptyValue || false;
-                }
-                if (typeof param.example !== undefined) {
-                    p.example = param.example;
-                }
-                if (param.examples) {
-                    p.examples = param.examples;
-                }
-                if (param.deprecated) {
-                    p.deprecated = param.deprecated;
-                }
-                if (param.contentType) {
-                    p.contentType = param.contentType;
-                }
-                p.in = (_a = param === null || param === void 0 ? void 0 : param.in) !== null && _a !== void 0 ? _a : p.in;
-                p.required = (_b = param === null || param === void 0 ? void 0 : param.required) !== null && _b !== void 0 ? _b : p.required;
-                if (p.in === 'query') {
-                    p.style = 'form';
-                }
-                else if (p.in === 'path' || p.in === 'header') {
-                    p.style = 'simple';
-                }
-                else if (p.in === 'cookie') {
-                    p.style = 'form';
-                }
-                p.explode = p.style === 'form';
-                // response content
-                if (param === null || param === void 0 ? void 0 : param.content) {
-                    p.content = param === null || param === void 0 ? void 0 : param.content;
-                }
-                if (param.schema) {
-                    p.schema = param.schema;
-                }
-                else {
-                    if (param.type) {
-                        if (core_1.Types.isClass(param.type)) {
-                            this.parseClzz(param.type);
-                            p.schema = {
-                                $ref: '#/components/schemas/' + param.type.name,
-                            };
-                        }
-                        if (param.isArray) {
-                            let ref;
-                            if ((_c = p === null || p === void 0 ? void 0 : p.schema) === null || _c === void 0 ? void 0 : _c.$ref) {
-                                ref = p.schema.$ref;
-                            }
-                            p.schema = {
-                                type: 'array',
-                                items: {
-                                    format: param.format,
-                                },
-                            };
-                            if (ref) {
-                                p.schema.items.$ref = ref;
-                            }
-                            else {
-                                p.schema.items.type = convertSchemaType(param.type);
-                            }
-                        }
-                        else {
-                            if (!p.schema) {
-                                p.schema = {
-                                    type: param.type ? convertSchemaType(param.type) : p.type,
-                                    format: param.format || p.format,
-                                };
-                            }
-                        }
-                    }
-                    else if (param.format) {
-                        p.schema.format = param.format;
-                    }
-                }
-            }
-        }
-    }
     /**
      * 解析 ApiExtraModel
      * @param clzz
@@ -1053,4 +980,35 @@ function parseTypeSchema(ref) {
             return ref;
     }
 }
+function parseTags(tags) {
+    let strTags = [];
+    if (tags.length > 0) {
+        for (const t of tags) {
+            // 这里 metadata => string[]
+            strTags = strTags.concat(t.metadata);
+        }
+    }
+    return strTags;
+}
+function addTag(newTag, tags = []) {
+    /**
+     * tag 结构
+     * ['name', 'description'] 或者 'name'
+     */
+    if (
+    // 处理重复的标签
+    tags.find(t => {
+        if (Array.isArray(newTag)) {
+            return t === newTag[0];
+        }
+        else {
+            return t === newTag;
+        }
+    })) {
+        // ignore
+    }
+    else {
+        tags.push(newTag);
+    }
+}
 //# sourceMappingURL=swaggerExplorer.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midwayjs/swagger",
-  "version": "3.17.1",
+  "version": "3.17.3",
   "main": "dist/index.js",
   "typings": "index.d.ts",
   "files": [
@@ -13,7 +13,7 @@
     "@midwayjs/core": "^3.17.1",
     "@midwayjs/koa": "^3.17.1",
     "@midwayjs/mock": "^3.17.1",
-    "@midwayjs/validate": "^3.17.1",
+    "@midwayjs/validate": "^3.17.3",
     "swagger-ui-dist": "5.17.14"
   },
   "author": "Kurten Chan <chinkurten@gmail.com>",
@@ -27,5 +27,5 @@
     "type": "git",
     "url": "https://github.com/midwayjs/midway.git"
   },
-  "gitHead": "824d8474a425b342fcd4480649c83677f846afb9"
+  "gitHead": "f4086c0e118673052202ffa92149aacd89e9ddc5"
 }