@midwayjs/swagger 3.14.7 → 3.14.9-beta.1

package/dist/decorators/api-exclude-controller.decorator.js

@@ -4,7 +4,9 @@ exports.ApiExcludeController = void 0;
 const core_1 = require("@midwayjs/core");
 const constants_1 = require("../constants");
 function ApiExcludeController(disable = true) {
-    return (0, core_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_EXCLUDE_CONTROLLER, [disable], false);
+    return (target) => {
+        (0, core_1.saveClassMetadata)(constants_1.DECORATORS.API_EXCLUDE_CONTROLLER, { disable }, target);
+    };
 }
 exports.ApiExcludeController = ApiExcludeController;
 //# sourceMappingURL=api-exclude-controller.decorator.js.map

package/dist/documentBuilder.d.ts

@@ -11,6 +11,7 @@ export declare class DocumentBuilder {
     setExternalDoc(description: string, url: string): this;
     addPaths(paths: Record<string, PathItemObject>): this;
     getPaths(): PathsObject;
+    setPaths(paths: Record<string, PathItemObject>): this;
     addSchema(schema: Record<string, SchemaObject>): this;
     getSchema(name: string): SchemaObject;
     addTag(name: string, description?: string, externalDocs?: ExternalDocumentationObject): this;

package/dist/documentBuilder.js

@@ -56,6 +56,10 @@ class DocumentBuilder {
     getPaths() {
         return this.document.paths;
     }
+    setPaths(paths) {
+        this.document.paths = paths;
+        return this;
+    }
     addSchema(schema) {
         if (!this.document.components.schemas) {
             this.document.components.schemas = {};

package/dist/interfaces/index.d.ts

@@ -369,5 +369,9 @@ export interface SwaggerOptions {
         content: any;
     }>;
     swaggerUIRenderOptions?: Record<string, any>;
+    /**
+     * 自定义路由过滤器
+     */
+    routerFilter?: (url: string, options: RouterOption) => boolean;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/swaggerExplorer.js

@@ -16,6 +16,7 @@ const documentBuilder_1 = require("./documentBuilder");
 const _1 = require(".");
 let SwaggerExplorer = class SwaggerExplorer {
     constructor() {
+        this.swaggerConfig = {};
         this.documentBuilder = new documentBuilder_1.DocumentBuilder();
         this.operationIdFactory = (controllerKey, webRouter) => `${controllerKey.toLowerCase()}_${webRouter.method.toLocaleLowerCase()}`;
     }
@@ -80,7 +81,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                 newPaths[`${globalPrefix}${routerUrl}`] = value;
             }
         }
-        this.documentBuilder.addPaths(newPaths);
+        this.documentBuilder.setPaths(newPaths);
     }
     scanApp() {
         var _a;
@@ -96,17 +97,26 @@ let SwaggerExplorer = class SwaggerExplorer {
         return this.documentBuilder.build();
     }
     generatePath(target) {
-        this.parseExtraModel(target);
-        const metaForMethods = (0, core_1.getClassMetadata)(core_1.INJECT_CUSTOM_METHOD, target) || [];
-        const exs = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_EXCLUDE_CONTROLLER);
-        if (exs[0]) {
+        // 获取控制器元数据
+        const excludeClassMeta = (0, core_1.getClassMetadata)(constants_1.DECORATORS.API_EXCLUDE_CONTROLLER, target);
+        if (excludeClassMeta && excludeClassMeta.disable) {
+            // 如果存在需要排除的控制器，则直接返回
             return;
         }
+        // 解析额外的模型
+        this.parseExtraModel(target);
+        // 获取方法的元数据
+        const metaForClass = (0, core_1.getClassMetadata)(core_1.INJECT_CUSTOM_METHOD, target) || [];
+        // 获取参数的元数据
         const metaForParams = (0, core_1.getClassMetadata)(core_1.INJECT_CUSTOM_PARAM, target) || [];
+        // 获取控制器选项
         const controllerOption = (0, core_1.getClassMetadata)(core_1.CONTROLLER_KEY, target);
+        // 获取前缀
         const prefix = controllerOption.prefix;
-        const tags = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_TAGS);
+        // 过滤出标签
+        const tags = metaForClass.filter(item => item.key === constants_1.DECORATORS.API_TAGS);
         let strTags = [];
+        // 如果存在标签，则将其添加到文档构建器中
         if (tags.length > 0) {
             for (const t of tags) {
                 // 这里 metadata => string[]
@@ -115,6 +125,7 @@ let SwaggerExplorer = class SwaggerExplorer {
             }
         }
         else {
+            // 如果不存在标签，则根据控制器选项生成标签
             const tag = { name: '', description: '' };
             if (prefix !== '/') {
                 tag.name =
@@ -128,53 +139,71 @@ let SwaggerExplorer = class SwaggerExplorer {
                 tag.description =
                     (controllerOption === null || controllerOption === void 0 ? void 0 : controllerOption.routerOptions.description) || tag.name;
             }
+            // 如果标签名存在，则将其添加到文档构建器中
             if (tag.name) {
                 strTags.push(tag.name);
                 this.documentBuilder.addTag(tag.name, tag.description);
             }
         }
-        // const globalMiddleware = controllerOption.routerOptions.middleware;
-        // get router info
+        // 获取路由信息
         const webRouterInfo = (0, core_1.getClassMetadata)(core_1.WEB_ROUTER_KEY, target);
-        let headers = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_HEADERS);
+        // 过滤出头部信息
+        let headers = metaForClass.filter(item => item.key === constants_1.DECORATORS.API_HEADERS);
         if (headers.length > 0) {
             headers = headers.map(item => item.metadata);
         }
-        const security = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_SECURITY);
+        // 过滤出安全信息
+        const security = metaForClass.filter(item => item.key === constants_1.DECORATORS.API_SECURITY);
+        // 初始化路径对象
         const paths = {};
+        // 如果存在路由信息，则遍历生成路径
         if (webRouterInfo && typeof webRouterInfo[Symbol.iterator] === 'function') {
             for (const webRouter of webRouterInfo) {
+                // 生成URL
                 let url = (prefix + webRouter.path).replace('//', '/');
                 url = replaceUrl(url, parseParamsInPath(url));
                 // 判断是否忽略当前路由
-                const endpoints = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_EXCLUDE_ENDPOINT &&
+                const endpoints = metaForClass.filter(item => item.key === constants_1.DECORATORS.API_EXCLUDE_ENDPOINT &&
                     item.propertyName === webRouter.method);
+                // 如果存在需要忽略的路由，则跳过当前循环
                 if (endpoints[0]) {
                     continue;
                 }
+                // 判断是否需要过滤当前路由
+                if (this.swaggerConfig.routerFilter) {
+                    const isFilter = this.swaggerConfig.routerFilter(url, webRouter);
+                    if (isFilter) {
+                        continue;
+                    }
+                }
+                // 获取路由参数
                 const routerArgs = metaForParams[webRouter.method] || [];
+                // 过滤出主体参数
                 const bds = routerArgs.filter(item => {
                     var _a;
                     return item.key === core_1.WEB_ROUTER_PARAM_KEY &&
                         ((_a = item === null || item === void 0 ? void 0 : item.metadata) === null || _a === void 0 ? void 0 : _a.type) === core_1.RouteParamTypes.BODY;
                 });
+                // 如果存在多个主体参数，则跳过当前循环，因为swagger不支持多个@Body
                 if (bds.length > 1) {
-                    // swagger not support more than one @Body
                     continue;
                 }
-                this.generateRouteMethod(url, webRouter, paths, metaForMethods, routerArgs, headers, target);
-                // 这里赋值 tags
+                // 生成路由方法
+                this.generateRouteMethod(url, webRouter, paths, metaForClass, routerArgs, headers, target);
+                // 如果当前路径的标签长度为0，则赋值标签
                 if (paths[url][webRouter.requestMethod].tags.length === 0) {
                     paths[url][webRouter.requestMethod].tags = strTags;
                 }
-                // extension => prefix 为 x-
-                const exts = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_EXTENSION &&
+                // 过滤出扩展信息
+                const exts = metaForClass.filter(item => item.key === constants_1.DECORATORS.API_EXTENSION &&
                     item.propertyName === webRouter.method);
+                // 如果存在扩展信息，则将其添加到路径中
                 for (const e of exts) {
                     if (e.metadata) {
                         Object.assign(paths[url][webRouter.requestMethod], e.metadata);
                     }
                 }
+                // 如果存在安全信息，则将其添加到路径中
                 if (security.length > 0) {
                     if (!paths[url][webRouter.requestMethod].security) {
                         paths[url][webRouter.requestMethod].security = [];
@@ -188,6 +217,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                 }
             }
         }
+        // 将路径添加到文档构建器中
         this.documentBuilder.addPaths(paths);
     }
     /**

package/dist/swaggerMiddleware.js

@@ -20,7 +20,7 @@ let SwaggerMiddleware = class SwaggerMiddleware {
         this.swaggerRender = this.swaggerConfig.swaggerUIRender(this.swaggerConfig, this.swaggerExplorer);
     }
     resolve(app) {
-        if (app.getFrameworkType() === core_1.MidwayFrameworkType.WEB_EXPRESS) {
+        if (app.getNamespace() === 'express') {
             return async (req, res, next) => {
                 const pathname = req.path;
                 const renderResult = await this.swaggerRender(pathname);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midwayjs/swagger",
-  "version": "3.14.7",
+  "version": "3.14.9-beta.1",
   "main": "dist/index.js",
   "typings": "index.d.ts",
   "files": [
@@ -27,6 +27,5 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/midwayjs/midway.git"
-  },
-  "gitHead": "148356ccd4b97404dde43d4a06edd51da039828a"
+  }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2013 - Now midwayjs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.