@midwayjs/swagger 3.0.0-beta.9 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -1,5 +1,7 @@
 # midwayjs swagger module
 
+## Thanks to [@nestjs/swagger](https://github.com/nestjs/swagger)
+
 [![Package Quality](http://npm.packagequality.com/shield/midway-core.svg)](http://packagequality.com/#?package=midway-core)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/midwayjs/midway/pulls)
 

package/dist/decorators/api-body.decorator.d.ts

@@ -1,10 +1,18 @@
 import { ContentObject, ExamplesObject, ReferenceObject, RequestBodyObject, SchemaObject, SwaggerEnumType } from '../interfaces';
 declare type RequestBodyOptions = Omit<RequestBodyObject, 'content'>;
+export declare enum BodyContentType {
+    FormUrlEncoded = "application/x-www-form-urlencoded",
+    JSON = "application/json",
+    Multipart = "multipart/form-data",
+    MultipartMixed = "multipart/mixed",
+    OctetStream = "application/octet-stream"
+}
 interface ApiBodyMetadata extends RequestBodyOptions {
     type?: any;
     isArray?: boolean;
     enum?: SwaggerEnumType;
     content?: ContentObject;
+    contentType?: BodyContentType;
 }
 interface ApiBodySchemaHost extends RequestBodyOptions {
     schema: SchemaObject | ReferenceObject;

package/dist/decorators/api-body.decorator.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiBody = void 0;
+exports.ApiBody = exports.BodyContentType = void 0;
 const enum_utils_1 = require("../common/enum.utils");
 const helpers_1 = require("./helpers");
+var BodyContentType;
+(function (BodyContentType) {
+    BodyContentType["FormUrlEncoded"] = "application/x-www-form-urlencoded";
+    BodyContentType["JSON"] = "application/json";
+    BodyContentType["Multipart"] = "multipart/form-data";
+    BodyContentType["MultipartMixed"] = "multipart/mixed";
+    BodyContentType["OctetStream"] = "application/octet-stream";
+})(BodyContentType = exports.BodyContentType || (exports.BodyContentType = {}));
 const defaultBodyMetadata = {
     type: String,
     required: true,

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

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

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

@@ -6,7 +6,7 @@ const constants_1 = require("../constants");
 function ApiExcludeEndpoint(disable = true) {
     return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_EXCLUDE_ENDPOINT, {
         disable,
-    });
+    }, false);
 }
 exports.ApiExcludeEndpoint = ApiExcludeEndpoint;
 //# sourceMappingURL=api-exclude-endpoint.decorator.js.map

package/dist/decorators/api-header.decorator.js

@@ -30,7 +30,7 @@ function ApiHeader(options) {
         if (descriptor) {
             return (0, helpers_1.createParamDecorator)(param, defaultHeaderOptions)(target, key, descriptor);
         }
-        return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_HEADERS, param)(target, undefined, undefined);
+        return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_HEADERS, param, false)(target, undefined, undefined);
     };
 }
 exports.ApiHeader = ApiHeader;

package/dist/decorators/api-operation.decorator.js

@@ -10,7 +10,7 @@ function ApiOperation(options) {
     return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_OPERATION, {
         ...defaultOperationOptions,
         ...options,
-    });
+    }, false);
 }
 exports.ApiOperation = ApiOperation;
 //# sourceMappingURL=api-operation.decorator.js.map

package/dist/decorators/api-property.decorator.js

@@ -14,7 +14,6 @@ function createApiPropertyDecorator(options = {}) {
     options = {
         ...options,
         type,
-        isArray,
     };
     if (isEnumArray(options)) {
         options.type = 'array';
@@ -30,10 +29,10 @@ function createApiPropertyDecorator(options = {}) {
         options.enum = enumValues;
         options.type = (0, enum_utils_1.getEnumType)(enumValues);
     }
-    if (Array.isArray(options.type)) {
+    if (isArray) {
         options.type = 'array';
         options.items = {
-            type: options.type[0],
+            type: type,
         };
     }
     return (0, helpers_1.createPropertyDecorator)(constants_1.DECORATORS.API_MODEL_PROPERTIES, options);

package/dist/decorators/api-response.decorator.js

@@ -13,7 +13,7 @@ function ApiResponse(options) {
     const groupedMetadata = {
         [options.status || 'default']: options,
     };
-    return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_RESPONSE, groupedMetadata);
+    return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_RESPONSE, groupedMetadata, false);
 }
 exports.ApiResponse = ApiResponse;
 const ApiOkResponse = (options = {}) => ApiResponse({

package/dist/decorators/api-security.decorator.js

@@ -11,7 +11,7 @@ function ApiSecurity(name, requirements = []) {
     else {
         metadata = name;
     }
-    return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_SECURITY, metadata);
+    return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_SECURITY, metadata, false);
 }
 exports.ApiSecurity = ApiSecurity;
 //# sourceMappingURL=api-security.decorator.js.map

package/dist/decorators/helpers.js

@@ -4,18 +4,18 @@ exports.getSchemaPath = exports.getTypeIsArrayTuple = exports.createParamDecorat
 const decorator_1 = require("@midwayjs/decorator");
 const constants_1 = require("../constants");
 function createPropertyDecorator(metakey, metadata) {
-    return (0, decorator_1.createCustomPropertyDecorator)(metakey, metadata);
+    return (0, decorator_1.createCustomPropertyDecorator)(metakey, metadata, false);
 }
 exports.createPropertyDecorator = createPropertyDecorator;
 function createMixedDecorator(metakey, metadata) {
-    return (0, decorator_1.createCustomMethodDecorator)(metakey, metadata);
+    return (0, decorator_1.createCustomMethodDecorator)(metakey, metadata, false);
 }
 exports.createMixedDecorator = createMixedDecorator;
 function createParamDecorator(metadata, initial) {
     return (0, decorator_1.createCustomMethodDecorator)(constants_1.DECORATORS.API_PARAMETERS, {
         ...initial,
         ...metadata,
-    });
+    }, false);
 }
 exports.createParamDecorator = createParamDecorator;
 function getTypeIsArrayTuple(input, isArrayFlag) {

package/dist/documentBuilder.d.ts

@@ -9,9 +9,10 @@ export declare class DocumentBuilder {
     setLicense(name: string, url: string): this;
     addServer(url: string, description?: string, variables?: Record<string, ServerVariableObject>): this;
     setExternalDoc(description: string, url: string): this;
-    setBasePath(path: string): this;
+    setBasePath(path: string | string[]): this;
     addPaths(paths: Record<string, PathItemObject>): this;
     addSchema(schema: Record<string, SchemaObject>): this;
+    getSchema(name: string): SchemaObject;
     addTag(name: string, description?: string, externalDocs?: ExternalDocumentationObject): this;
     addSecurity(name: string, options: SecuritySchemeObject): this;
     addSecurityRequirements(name: string | SecurityRequirementObject, requirements?: string[]): this;
@@ -20,6 +21,7 @@ export declare class DocumentBuilder {
     addApiKey(options?: SecuritySchemeObject, name?: string): this;
     addBasicAuth(options?: SecuritySchemeObject, name?: string): this;
     addCookieAuth(cookieName?: string, options?: SecuritySchemeObject, securityName?: string): this;
+    sortTags(): void;
     build(): Omit<OpenAPIObject, 'paths'>;
 }
 //# sourceMappingURL=documentBuilder.d.ts.map

package/dist/documentBuilder.js

@@ -77,6 +77,13 @@ class DocumentBuilder {
         Object.assign(this.document.components.schemas, schema);
         return this;
     }
+    getSchema(name) {
+        var _a, _b;
+        if ((_a = this.document.components) === null || _a === void 0 ? void 0 : _a.schemas) {
+            return (_b = this.document.components) === null || _b === void 0 ? void 0 : _b.schemas[name];
+        }
+        return undefined;
+    }
     addTag(name, description = '', externalDocs) {
         if (Array.isArray(name)) {
             const arr = name;
@@ -184,6 +191,23 @@ class DocumentBuilder {
         });
         return this;
     }
+    sortTags() {
+        const tags = this.document.tags;
+        this.document.tags = tags.sort((a, b) => {
+            const s1 = a.name;
+            const s2 = b.name;
+            const len = s1.length > s2.length ? s2.length : s1.length;
+            for (let i = 0; i < len; i++) {
+                if (s1.charCodeAt(i) > s2.charCodeAt(i)) {
+                    return 1;
+                }
+                else if (s1.charCodeAt(i) < s2.charCodeAt(i)) {
+                    return -1;
+                }
+            }
+            return 0;
+        });
+    }
     build() {
         return this.document;
     }

package/dist/interfaces/index.d.ts

@@ -251,18 +251,94 @@ export interface SchemaObjectMetadata extends Omit<SchemaObject, 'type' | 'requi
     name?: string;
     enumName?: string;
 }
+export declare type AuthType = 'basic' | 'bearer' | 'cookie' | 'oauth2' | 'apikey' | 'custom';
+/**
+ * 继承自 https://swagger.io/specification/#security-scheme-object
+ */
+export interface AuthOptions extends Omit<SecuritySchemeObject, 'type'> {
+    /**
+     * 验权类型
+     * basic  => http basic 验证
+     * bearer => http jwt 验证
+     * cookie => cookie 方式验证
+     * oauth2 => 使用 oauth2
+     * apikey => apiKey
+     * custom => 自定义方式
+     */
+    authType: AuthType;
+    /**
+     * https://swagger.io/specification/#security-scheme-object type 字段
+     */
+    type?: SecuritySchemeType;
+    /**
+     * authType = cookie 时可以修改，通过 ApiCookie 装饰器关联的名称
+     */
+    securityName?: string;
+    /**
+     * authType = cookie 时可以修改，cookie 的名称
+     */
+    cookieName?: string;
+}
+/**
+ * see https://swagger.io/specification/
+ */
 export interface SwaggerOptions {
+    /**
+     * 默认值: My Project
+     * https://swagger.io/specification/#info-object title 字段
+     */
     title?: string;
+    /**
+     * 默认值: This is a swagger-ui for midwayjs project
+     * https://swagger.io/specification/#info-object description 字段
+     */
     description?: string;
+    /**
+     * 默认值: 1.0.0
+     * https://swagger.io/specification/#info-object version 字段
+     */
     version?: string;
-    swaggerPath?: string;
+    /**
+     * https://swagger.io/specification/#info-object contact 字段
+     */
     contact?: ContactObject;
+    /**
+     * https://swagger.io/specification/#info-object license 字段
+     */
     license?: LicenseObject;
-    basePath?: string;
+    /**
+     * https://swagger.io/specification/#info-object termsOfService 字段
+     */
     termsOfService?: string;
-    externalDoc?: ExternalDocumentationObject;
+    /**
+     * https://swagger.io/specification/#openapi-object externalDocs 字段
+     */
+    externalDocs?: ExternalDocumentationObject;
+    /**
+     * https://swagger.io/specification/#openapi-object servers 字段
+     */
     servers?: Array<ServerObject>;
+    /**
+     * https://swagger.io/specification/#openapi-object tags 字段
+     */
     tags?: Array<TagObject>;
-    auth?: SecuritySchemeObject;
+    /**
+     * 可以参考 https://swagger.io/specification/#security-scheme-object
+     */
+    auth?: AuthOptions | AuthOptions[];
+    /**
+     * api 的 根路径
+     */
+    basePath?: string | string[];
+    /**
+     * 默认值: /swagger-ui
+     * 访问 swagger ui 的路径
+     */
+    swaggerPath?: string;
+    /**
+     * 对路由 tag 进行 ascii 排序
+     * 可以使用 1-xxx、2-xxx、3-xxx 来定义 tag
+     */
+    tagSortable?: boolean;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/swaggerExplorer.js

@@ -13,12 +13,13 @@ exports.SwaggerExplorer = void 0;
 const decorator_1 = require("@midwayjs/decorator");
 const constants_1 = require("./constants");
 const documentBuilder_1 = require("./documentBuilder");
+const _1 = require(".");
 let SwaggerExplorer = class SwaggerExplorer {
     constructor() {
         this.documentBuilder = new documentBuilder_1.DocumentBuilder();
     }
     async init() {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _2, _3, _4, _5;
         this.documentBuilder.setTitle(this.swaggerConfig.title);
         this.documentBuilder.setVersion(this.swaggerConfig.version);
         this.documentBuilder.setDescription(this.swaggerConfig.description);
@@ -36,9 +37,9 @@ let SwaggerExplorer = class SwaggerExplorer {
         if (this.swaggerConfig.termsOfService) {
             this.documentBuilder.setTermsOfService(this.swaggerConfig.termsOfService);
         }
-        if (((_q = this.swaggerConfig) === null || _q === void 0 ? void 0 : _q.externalDoc) &&
-            typeof ((_r = this.swaggerConfig) === null || _r === void 0 ? void 0 : _r.externalDoc) === 'object') {
-            this.documentBuilder.setExternalDoc((_t = (_s = this.swaggerConfig) === null || _s === void 0 ? void 0 : _s.externalDoc) === null || _t === void 0 ? void 0 : _t.description, (_v = (_u = this.swaggerConfig) === null || _u === void 0 ? void 0 : _u.externalDoc) === null || _v === void 0 ? void 0 : _v.url);
+        if (((_q = this.swaggerConfig) === null || _q === void 0 ? void 0 : _q.externalDocs) &&
+            typeof ((_r = this.swaggerConfig) === null || _r === void 0 ? void 0 : _r.externalDocs) === 'object') {
+            this.documentBuilder.setExternalDoc((_t = (_s = this.swaggerConfig) === null || _s === void 0 ? void 0 : _s.externalDocs) === null || _t === void 0 ? void 0 : _t.description, (_v = (_u = this.swaggerConfig) === null || _u === void 0 ? void 0 : _u.externalDocs) === null || _v === void 0 ? void 0 : _v.url);
         }
         if (((_w = this.swaggerConfig) === null || _w === void 0 ? void 0 : _w.servers) &&
             Array.isArray((_x = this.swaggerConfig) === null || _x === void 0 ? void 0 : _x.servers)) {
@@ -47,25 +48,29 @@ let SwaggerExplorer = class SwaggerExplorer {
             }
         }
         if (((_z = this.swaggerConfig) === null || _z === void 0 ? void 0 : _z.tags) && Array.isArray((_0 = this.swaggerConfig) === null || _0 === void 0 ? void 0 : _0.tags)) {
-            for (const t of (_1 = this.swaggerConfig) === null || _1 === void 0 ? void 0 : _1.tags) {
+            for (const t of (_2 = this.swaggerConfig) === null || _2 === void 0 ? void 0 : _2.tags) {
                 this.documentBuilder.addTag(t.name, t.description, t.externalDocs);
             }
         }
         // 设置 auth 类型
-        if (Array.isArray((_2 = this.swaggerConfig) === null || _2 === void 0 ? void 0 : _2.auth)) {
-            for (const a of (_3 = this.swaggerConfig) === null || _3 === void 0 ? void 0 : _3.auth) {
+        if (Array.isArray((_3 = this.swaggerConfig) === null || _3 === void 0 ? void 0 : _3.auth)) {
+            for (const a of (_4 = this.swaggerConfig) === null || _4 === void 0 ? void 0 : _4.auth) {
                 this.setAuth(a);
             }
         }
         else {
-            this.setAuth((_4 = this.swaggerConfig) === null || _4 === void 0 ? void 0 : _4.auth);
+            this.setAuth((_5 = this.swaggerConfig) === null || _5 === void 0 ? void 0 : _5.auth);
         }
     }
     scanApp() {
+        var _a;
         const routes = (0, decorator_1.listModule)(decorator_1.CONTROLLER_KEY);
         for (const route of routes) {
             this.generatePath(route);
         }
+        if ((_a = this.swaggerConfig) === null || _a === void 0 ? void 0 : _a.tagSortable) {
+            this.documentBuilder.sortTags();
+        }
     }
     getData() {
         return this.documentBuilder.build();
@@ -98,11 +103,12 @@ let SwaggerExplorer = class SwaggerExplorer {
                     (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) || 'default';
+                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);
                 this.documentBuilder.addTag(tag.name, tag.description);
             }
         }
@@ -158,7 +164,7 @@ let SwaggerExplorer = class SwaggerExplorer {
      * 构造 router 提取方法
      */
     generateRouteMethod(url, webRouter, paths, metaForMethods, metaForParams, header, target) {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         const operMeta = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_OPERATION &&
             item.propertyName === webRouter.method)[0];
         let opts = paths[url];
@@ -196,7 +202,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                     continue;
                 }
             }
-            if ((0, decorator_1.isClass)(currentType)) {
+            if (decorator_1.Types.isClass(currentType)) {
                 this.parseClzz(currentType);
                 p.schema = {
                     $ref: '#/components/schemas/' + currentType.name,
@@ -209,16 +215,66 @@ let SwaggerExplorer = class SwaggerExplorer {
             }
             this.parseFromParamsToP(params[params.length - 1 - arg.parameterIndex], p);
             if (p.in === 'body') {
-                const requestBody = {
-                    required: true,
-                    description: p.description || p.name,
-                    content: p.content || {
-                        'application/json': {
-                            schema: p.schema,
+                // 这里兼容一下 @File()、@Files()、@Fields() 装饰器
+                if (((_j = arg.metadata) === null || _j === void 0 ? void 0 : _j.type) === decorator_1.RouteParamTypes.FILESSTREAM) {
+                    p.schema = {
+                        type: 'object',
+                        properties: {
+                            files: {
+                                type: 'array',
+                                items: {
+                                    type: 'string',
+                                    format: 'binary',
+                                },
+                                description: p.description,
+                            },
                         },
-                    },
-                };
-                opts[webRouter.requestMethod].requestBody = requestBody;
+                    };
+                    p.contentType = _1.BodyContentType.Multipart;
+                }
+                if (((_k = arg.metadata) === null || _k === void 0 ? void 0 : _k.type) === decorator_1.RouteParamTypes.FILESTREAM) {
+                    p.schema = {
+                        type: 'object',
+                        properties: {
+                            file: {
+                                type: 'string',
+                                format: 'binary',
+                                description: p.description,
+                            },
+                        },
+                    };
+                    p.contentType = _1.BodyContentType.Multipart;
+                }
+                if (((_l = arg.metadata) === null || _l === void 0 ? void 0 : _l.type) === decorator_1.RouteParamTypes.FIELDS) {
+                    if (p.schema['$ref']) {
+                        // 展开各个字段属性
+                        const name = p.schema['$ref'].replace('#/components/schemas/', '');
+                        const schema = this.documentBuilder.getSchema(name);
+                        delete p.schema['$ref'];
+                        p.schema = JSON.parse(JSON.stringify(schema));
+                    }
+                    p.contentType = _1.BodyContentType.Multipart;
+                }
+                if (!p.content) {
+                    p.content = {};
+                    p.content[p.contentType || 'application/json'] = {
+                        schema: p.schema,
+                    };
+                }
+                if (!opts[webRouter.requestMethod].requestBody) {
+                    const requestBody = {
+                        required: true,
+                        description: p.description || p.name,
+                        content: p.content,
+                    };
+                    opts[webRouter.requestMethod].requestBody = requestBody;
+                }
+                else {
+                    // 这里拼 schema properties 时肯定存在
+                    Object.assign(opts[webRouter.requestMethod].requestBody.content[p.contentType]
+                        .schema.properties, p.schema.properties);
+                }
+                delete p.contentType;
                 delete p.content;
                 // in body 不需要处理
                 continue;
@@ -230,9 +286,9 @@ let SwaggerExplorer = class SwaggerExplorer {
             parameters.unshift(header);
         }
         opts[webRouter.requestMethod].parameters = parameters;
-        opts[webRouter.requestMethod].responses = {};
         const responses = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_RESPONSE &&
             item.propertyName === webRouter.method);
+        const returnResponses = {};
         for (const r of responses) {
             const resp = r.metadata;
             const keys = Object.keys(resp);
@@ -240,7 +296,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                 // 这里是引用，赋值可以直接更改
                 const tt = resp[k];
                 if (tt.type) {
-                    if ((0, decorator_1.isClass)(tt.type)) {
+                    if (decorator_1.Types.isClass(tt.type)) {
                         this.parseClzz(tt.type);
                         if (tt.isArray) {
                             tt.content = {
@@ -279,7 +335,17 @@ let SwaggerExplorer = class SwaggerExplorer {
                 delete tt.isArray;
                 delete tt.format;
             }
-            Object.assign(opts[webRouter.requestMethod].responses, resp);
+            Object.assign(returnResponses, resp);
+        }
+        if (Object.keys(returnResponses).length > 0) {
+            opts[webRouter.requestMethod].responses = returnResponses;
+        }
+        else {
+            opts[webRouter.requestMethod].responses = {
+                200: {
+                    description: 'OK',
+                },
+            };
         }
         paths[url] = opts;
     }
@@ -306,6 +372,9 @@ let SwaggerExplorer = class SwaggerExplorer {
                 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') {
@@ -327,7 +396,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                 }
                 else {
                     if (param.type) {
-                        if ((0, decorator_1.isClass)(param.type)) {
+                        if (decorator_1.Types.isClass(param.type)) {
                             this.parseClzz(param.type);
                             p.schema = {
                                 $ref: '#/components/schemas/' + param.type.name,
@@ -363,45 +432,65 @@ let SwaggerExplorer = class SwaggerExplorer {
      * @param clzz
      */
     parseClzz(clzz) {
+        if (this.documentBuilder.getSchema(clzz.name)) {
+            return;
+        }
         const props = (0, decorator_1.getClassMetadata)(decorator_1.INJECT_CUSTOM_PROPERTY, clzz);
+        const tt = {
+            type: 'object',
+            properties: {},
+        };
         if (props) {
-            const tt = {
-                type: 'object',
-                properties: {},
-                required: [],
-                example: {},
-            };
             Object.keys(props).forEach(key => {
-                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
-                if ((_a = props[key].metadata) === null || _a === void 0 ? void 0 : _a.example) {
-                    tt.example[key] = (_b = props[key].metadata) === null || _b === void 0 ? void 0 : _b.example;
+                var _a, _b;
+                const metadata = props[key].metadata;
+                if (metadata === null || metadata === void 0 ? void 0 : metadata.example) {
+                    if (!tt.example) {
+                        tt.example = {};
+                    }
+                    tt.example[key] = metadata === null || metadata === void 0 ? void 0 : metadata.example;
+                    delete metadata.example;
                 }
-                if (((_c = props[key].metadata) === null || _c === void 0 ? void 0 : _c.required) !== false) {
+                if ((metadata === null || metadata === void 0 ? void 0 : metadata.required) !== false) {
+                    if (!tt.required) {
+                        tt.required = [];
+                    }
                     tt.required.push(key);
+                    delete metadata.required;
                 }
-                if ((_d = props[key].metadata) === null || _d === void 0 ? void 0 : _d.enum) {
+                if (metadata === null || metadata === void 0 ? void 0 : metadata.enum) {
                     tt.properties[key] = {
-                        type: (_e = props[key].metadata) === null || _e === void 0 ? void 0 : _e.type,
-                        enum: (_f = props[key].metadata) === null || _f === void 0 ? void 0 : _f.enum,
-                        default: (_g = props[key].metadata) === null || _g === void 0 ? void 0 : _g.default,
+                        type: metadata === null || metadata === void 0 ? void 0 : metadata.type,
+                        enum: metadata === null || metadata === void 0 ? void 0 : metadata.enum,
+                        default: metadata === null || metadata === void 0 ? void 0 : metadata.default,
                     };
+                    if (metadata === null || metadata === void 0 ? void 0 : metadata.description) {
+                        tt.properties[key].description = metadata === null || metadata === void 0 ? void 0 : metadata.description;
+                    }
                     return;
                 }
-                if ((_j = (_h = props[key].metadata) === null || _h === void 0 ? void 0 : _h.items) === null || _j === void 0 ? void 0 : _j.enum) {
+                if ((_a = metadata === null || metadata === void 0 ? void 0 : metadata.items) === null || _a === void 0 ? void 0 : _a.enum) {
                     tt.properties[key] = {
-                        type: (_k = props[key].metadata) === null || _k === void 0 ? void 0 : _k.type,
-                        items: (_l = props[key].metadata) === null || _l === void 0 ? void 0 : _l.items,
-                        default: (_m = props[key].metadata) === null || _m === void 0 ? void 0 : _m.default,
+                        type: metadata === null || metadata === void 0 ? void 0 : metadata.type,
+                        items: metadata === null || metadata === void 0 ? void 0 : metadata.items,
+                        default: metadata === null || metadata === void 0 ? void 0 : metadata.default,
                     };
+                    if (metadata === null || metadata === void 0 ? void 0 : metadata.description) {
+                        tt.properties[key].description = metadata === null || metadata === void 0 ? void 0 : metadata.description;
+                    }
                     return;
                 }
-                let currentType = (_o = props[key].metadata) === null || _o === void 0 ? void 0 : _o.type;
+                let isArray = false;
+                let currentType = metadata === null || metadata === void 0 ? void 0 : metadata.type;
+                metadata === null || metadata === void 0 ? true : delete metadata.type;
                 if (currentType === 'array') {
-                    currentType = (_q = (_p = props[key].metadata) === null || _p === void 0 ? void 0 : _p.items) === null || _q === void 0 ? void 0 : _q.type;
+                    isArray = true;
+                    currentType = (_b = metadata === null || metadata === void 0 ? void 0 : metadata.items) === null || _b === void 0 ? void 0 : _b.type;
+                    delete metadata.items;
                 }
-                if ((0, decorator_1.isClass)(currentType)) {
+                if (decorator_1.Types.isClass(currentType)) {
                     this.parseClzz(currentType);
-                    if (((_r = props[key].metadata) === null || _r === void 0 ? void 0 : _r.type) === 'array') {
+                    if (isArray) {
                         tt.properties[key] = {
                             type: 'array',
                             items: {
@@ -416,27 +505,28 @@ let SwaggerExplorer = class SwaggerExplorer {
                     }
                 }
                 else {
-                    if (((_s = props[key].metadata) === null || _s === void 0 ? void 0 : _s.type) === 'array') {
+                    if (isArray) {
                         tt.properties[key] = {
                             type: 'array',
                             items: {
-                                type: (0, decorator_1.getPropertyType)(clzz.prototype, key).name,
-                                format: (_t = props[key].metadata) === null || _t === void 0 ? void 0 : _t.format,
+                                type: convertSchemaType((currentType === null || currentType === void 0 ? void 0 : currentType.name) || currentType),
                             },
                         };
                     }
                     else {
                         tt.properties[key] = {
                             type: (0, decorator_1.getPropertyType)(clzz.prototype, key).name,
-                            format: (_u = props[key].metadata) === null || _u === void 0 ? void 0 : _u.format,
+                            format: metadata === null || metadata === void 0 ? void 0 : metadata.format,
                         };
+                        delete metadata.format;
                     }
                 }
-            });
-            this.documentBuilder.addSchema({
-                [clzz.name]: tt,
+                Object.assign(tt.properties[key], metadata);
             });
         }
+        this.documentBuilder.addSchema({
+            [clzz.name]: tt,
+        });
     }
     /**
      * 授权验证
@@ -545,6 +635,9 @@ function convertTypeToString(type) {
         case decorator_1.RouteParamTypes.PARAM:
             return 'path';
         case decorator_1.RouteParamTypes.BODY:
+        case decorator_1.RouteParamTypes.FIELDS:
+        case decorator_1.RouteParamTypes.FILESSTREAM:
+        case decorator_1.RouteParamTypes.FILESTREAM:
             return 'body';
         default:
             return 'header';
@@ -561,7 +654,7 @@ function convertSchemaType(value) {
         case 'String':
             return 'string';
         default:
-            return 'object';
+            return value;
     }
 }
 //# sourceMappingURL=swaggerExplorer.js.map

package/dist/swaggerMiddleware.d.ts

@@ -5,5 +5,6 @@ export declare class SwaggerMiddleware implements IMiddleware<IMidwayContext, Ne
     private swaggerExplorer;
     init(): Promise<void>;
     resolve(app: IMidwayApplication): (req: any, res: any, next: NextFunction) => Promise<any>;
+    static getName(): string;
 }
 //# sourceMappingURL=swaggerMiddleware.d.ts.map

package/dist/swaggerMiddleware.js

@@ -100,6 +100,9 @@ let SwaggerMiddleware = class SwaggerMiddleware {
             };
         }
     }
+    static getName() {
+        return 'swagger';
+    }
 };
 __decorate([
     (0, decorator_1.Config)('swagger'),

package/index.d.ts

@@ -3,6 +3,6 @@ export * from './dist/index';
 
 declare module '@midwayjs/core/dist/interface' {
   interface MidwayConfig {
-    swagger: Partial<SwaggerOptions>;
+    swagger?: Partial<SwaggerOptions>;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midwayjs/swagger",
-  "version": "3.0.0-beta.9",
+  "version": "3.0.0",
   "main": "dist/index",
   "typings": "index.d.ts",
   "files": [
@@ -8,24 +8,24 @@
     "dist/**/*.d.ts",
     "index.d.ts"
   ],
-  "dependencies": { },
   "devDependencies": {
-    "swagger-ui-dist": "^3.34.0",
-    "@midwayjs/core": "^3.0.0-beta.9",
-    "@midwayjs/decorator": "^3.0.0-beta.9",
-    "@midwayjs/koa": "^3.0.0-beta.9",
-    "@midwayjs/mock": "^3.0.0-beta.9"
+    "@midwayjs/core": "^3.0.0",
+    "@midwayjs/decorator": "^3.0.0",
+    "@midwayjs/koa": "^3.0.0",
+    "@midwayjs/mock": "^3.0.0",
+    "swagger-ui-dist": "4.2.1"
   },
   "author": "Kurten Chan <chinkurten@gmail.com>",
   "license": "MIT",
   "scripts": {
     "build": "tsc",
     "jest": "node --require=ts-node/register ../../node_modules/jest/bin/jest.js",
-    "test": "node --require=ts-node/register ../../node_modules/.bin/jest",
-    "cov": "node --require=ts-node/register ../../node_modules/.bin/jest --coverage --forceExit"
+    "test": "node --require=ts-node/register ../../node_modules/.bin/jest --runInBand",
+    "cov": "node --require=ts-node/register ../../node_modules/.bin/jest --runInBand --coverage --forceExit"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/midwayjs/midway.git"
-  }
+  },
+  "gitHead": "55c26029bccf7bbb739fa1597e8f418dafa2caa0"
 }