@midwayjs/swagger 4.0.0-beta.8 → 4.0.0

package/dist/config/config.default.js

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

package/dist/interfaces/index.d.ts

@@ -381,6 +381,12 @@ export interface SwaggerOptions {
      * Weather to generate the Tag for controller
      */
     isGenerateTagForController?: boolean;
+    /**
+     * Enable inferring schema metadata from @midwayjs/validation DTO rules.
+     * When enabled, inferred metadata only fills fields that are not explicitly
+     * defined by @ApiProperty.
+     */
+    useValidationSchema?: boolean;
 }
 export interface MixDecoratorMetadata {
     key: string;

package/dist/swaggerExplorer.d.ts

@@ -15,6 +15,13 @@ export declare class SwaggerExplorer {
      * 构造 router 提取方法
      */
     private generateRouteMethod;
+    private upsertOperationParameter;
+    private cloneOpenAPIValue;
+    private normalizeContentSchemas;
+    private normalizeOperationParameters;
+    private normalizeOperationRequestBody;
+    private normalizeOperationResponse;
+    private normalizeOperationResponses;
     getOperationId(controllerKey: string, webRouter: RouterOption): string;
     /**
      * 解析 ApiExtraModel
@@ -52,6 +59,11 @@ export declare class SwaggerExplorer {
      * @param clzz
      */
     protected parseClzz(clzz: Type): any;
+    private mergePropertyMetadata;
+    protected getValidationSchemaHelper(): any;
+    private inferValidationProperties;
+    private inferValidateProperties;
+    protected hasClassValidatorMetadata(clzz: Type): boolean;
     /**
      * 授权验证
      * @param opts

package/dist/swaggerExplorer.js

@@ -15,6 +15,8 @@ const constants_1 = require("./constants");
 const documentBuilder_1 = require("./documentBuilder");
 const _1 = require(".");
 const enum_utils_1 = require("./common/enum.utils");
+const VALIDATION_RULES_KEY = 'validation:rules';
+const VALIDATE_RULES_KEY = 'common:rules';
 let SwaggerExplorer = class SwaggerExplorer {
     swaggerConfig = {};
     documentBuilder = new documentBuilder_1.DocumentBuilder();
@@ -38,14 +40,15 @@ let SwaggerExplorer = class SwaggerExplorer {
             typeof this.swaggerConfig?.externalDocs === 'object') {
             this.documentBuilder.setExternalDoc(this.swaggerConfig?.externalDocs?.description, this.swaggerConfig?.externalDocs?.url);
         }
-        if (this.swaggerConfig?.servers &&
-            Array.isArray(this.swaggerConfig?.servers)) {
-            for (const serv of this.swaggerConfig?.servers) {
+        const servers = this.swaggerConfig?.servers;
+        if (Array.isArray(servers)) {
+            for (const serv of servers) {
                 this.documentBuilder.addServer(serv?.url, serv?.description, serv?.variables);
             }
         }
-        if (this.swaggerConfig?.tags && Array.isArray(this.swaggerConfig?.tags)) {
-            for (const t of this.swaggerConfig?.tags) {
+        const tags = this.swaggerConfig?.tags;
+        if (Array.isArray(tags)) {
+            for (const t of tags) {
                 this.documentBuilder.addTag(t.name, t.description, t.externalDocs);
             }
         }
@@ -54,13 +57,14 @@ let SwaggerExplorer = class SwaggerExplorer {
                 this.swaggerConfig.documentOptions.operationIdFactory;
         }
         // 设置 auth 类型
-        if (Array.isArray(this.swaggerConfig?.auth)) {
-            for (const a of this.swaggerConfig?.auth) {
+        const authConfig = this.swaggerConfig?.auth;
+        if (Array.isArray(authConfig)) {
+            for (const a of authConfig) {
                 this.setAuth(a);
             }
         }
-        else {
-            this.setAuth(this.swaggerConfig?.auth);
+        else if (authConfig) {
+            this.setAuth(authConfig);
         }
     }
     addGlobalPrefix(globalPrefix) {
@@ -264,13 +268,19 @@ let SwaggerExplorer = class SwaggerExplorer {
         if (!opts) {
             opts = {};
         }
-        const parameters = [];
+        const operationParameters = this.normalizeOperationParameters(operMeta?.metadata?.parameters);
+        const operationRequestBody = this.normalizeOperationRequestBody(operMeta?.metadata?.requestBody);
+        const operationResponses = this.normalizeOperationResponses(operMeta?.metadata?.responses);
+        const parameters = [...operationParameters];
+        let requestBodyFromOperation = !!operationRequestBody;
         opts[webRouter.requestMethod] = {
             summary: getNotEmptyValue(operMeta?.metadata?.summary, webRouter.summary),
             description: getNotEmptyValue(operMeta?.metadata?.description, webRouter.description),
             operationId: operMeta?.metadata?.operationId ||
                 this.getOperationId(target.name, webRouter),
-            tags: routerTags.length ? routerTags : operMeta?.metadata?.tags ?? [],
+            tags: routerTags.length ? routerTags : (operMeta?.metadata?.tags ?? []),
+            ...(operationRequestBody ? { requestBody: operationRequestBody } : {}),
+            ...(operationResponses ? { responses: operationResponses } : {}),
         };
         if (operMeta?.metadata?.deprecated != null) {
             opts[webRouter.requestMethod].deprecated =
@@ -316,7 +326,7 @@ let SwaggerExplorer = class SwaggerExplorer {
             const p = param.metadata;
             p.schema = this.formatType(param.metadata.schema);
             if (p.in === 'query' || p.in === 'path' || p.in === 'header') {
-                parameters.push(p);
+                this.upsertOperationParameter(parameters, p);
             }
             else if (p.in === 'body') {
                 p.content = p.content ?? {};
@@ -332,13 +342,28 @@ let SwaggerExplorer = class SwaggerExplorer {
                 // if requestBody is already set, skip
                 opts[webRouter.requestMethod].requestBody =
                     opts[webRouter.requestMethod].requestBody ?? {};
-                opts[webRouter.requestMethod].requestBody.description =
-                    opts[webRouter.requestMethod].requestBody.description ??
-                        p.description;
-                opts[webRouter.requestMethod].requestBody.content =
-                    opts[webRouter.requestMethod].requestBody.content ?? p.content;
-                opts[webRouter.requestMethod].requestBody.required =
-                    opts[webRouter.requestMethod].requestBody.required ?? p.required;
+                if (requestBodyFromOperation) {
+                    if (p.description !== undefined) {
+                        opts[webRouter.requestMethod].requestBody.description =
+                            p.description;
+                    }
+                    if (p.content !== undefined) {
+                        opts[webRouter.requestMethod].requestBody.content = p.content;
+                    }
+                    if (p.required !== undefined) {
+                        opts[webRouter.requestMethod].requestBody.required = p.required;
+                    }
+                    requestBodyFromOperation = false;
+                }
+                else {
+                    opts[webRouter.requestMethod].requestBody.description =
+                        opts[webRouter.requestMethod].requestBody.description ??
+                            p.description;
+                    opts[webRouter.requestMethod].requestBody.content =
+                        opts[webRouter.requestMethod].requestBody.content ?? p.content;
+                    opts[webRouter.requestMethod].requestBody.required =
+                        opts[webRouter.requestMethod].requestBody.required ?? p.required;
+                }
             }
         }
         for (const arg of args) {
@@ -377,7 +402,7 @@ let SwaggerExplorer = class SwaggerExplorer {
                             schema: schema.properties[pName],
                             required: schema.required?.includes(pName) || false,
                         };
-                        parameters.push(pp);
+                        this.upsertOperationParameter(parameters, pp);
                     });
                     continue;
                 }
@@ -461,76 +486,23 @@ let SwaggerExplorer = class SwaggerExplorer {
                 // in body 不需要处理
                 continue;
             }
-            parameters.push(p);
+            this.upsertOperationParameter(parameters, p);
         }
         // class header 需要使用 ApiHeader 装饰器
         if (headers && headers.length) {
-            headers.forEach(header => parameters.unshift(header));
+            headers.forEach(header => this.upsertOperationParameter(parameters, header, true));
         }
         // 获取方法上的 @ApiHeader
         const methodHeaders = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_HEADERS);
         if (methodHeaders.length > 0) {
-            methodHeaders.forEach(item => parameters.unshift(item.metadata));
+            methodHeaders.forEach(item => this.upsertOperationParameter(parameters, item.metadata, true));
         }
         opts[webRouter.requestMethod].parameters = parameters;
         const responses = metaForMethods.filter(item => item.key === constants_1.DECORATORS.API_RESPONSE &&
             item.propertyName === webRouter.method);
-        const returnResponses = {};
+        const returnResponses = operationResponses ?? {};
         for (const r of responses) {
-            const resp = r.metadata;
-            const keys = Object.keys(resp);
-            for (const k of keys) {
-                // 这里是引用，赋值可以直接更改
-                const tt = resp[k];
-                if (tt.schema) {
-                    // response 的 schema 需要包含在 content 内
-                    tt.content = {
-                        'application/json': {
-                            schema: this.formatType(tt.schema),
-                        },
-                    };
-                    delete tt.schema;
-                }
-                else if (tt.type) {
-                    if (core_1.Types.isClass(tt.type)) {
-                        this.parseClzz(tt.type);
-                        if (tt.isArray) {
-                            tt.content = {
-                                'application/json': {
-                                    schema: {
-                                        type: 'array',
-                                        items: {
-                                            $ref: '#/components/schemas/' + tt.type.name,
-                                        },
-                                    },
-                                },
-                            };
-                        }
-                        else {
-                            tt.content = {
-                                'application/json': {
-                                    schema: {
-                                        $ref: '#/components/schemas/' + tt.type.name,
-                                    },
-                                },
-                            };
-                        }
-                    }
-                    else {
-                        tt.content = {
-                            'text/plain': {
-                                schema: {
-                                    type: convertSchemaType(tt.type),
-                                },
-                            },
-                        };
-                    }
-                }
-                delete tt.status;
-                delete tt.type;
-                delete tt.isArray;
-                delete tt.format;
-            }
+            const resp = this.normalizeOperationResponses(r.metadata);
             Object.assign(returnResponses, resp);
         }
         if (Object.keys(returnResponses).length > 0) {
@@ -545,6 +517,133 @@ let SwaggerExplorer = class SwaggerExplorer {
         }
         paths[url] = opts;
     }
+    upsertOperationParameter(parameters, parameter, prepend = false) {
+        const index = parameters.findIndex(item => {
+            return item?.name === parameter?.name && item?.in === parameter?.in;
+        });
+        if (index >= 0) {
+            parameters.splice(index, 1);
+        }
+        if (prepend) {
+            parameters.unshift(parameter);
+        }
+        else {
+            parameters.push(parameter);
+        }
+    }
+    cloneOpenAPIValue(value) {
+        if (Array.isArray(value)) {
+            return value.map(item => this.cloneOpenAPIValue(item));
+        }
+        if (value && typeof value === 'object') {
+            const cloned = {};
+            for (const key in value) {
+                cloned[key] = this.cloneOpenAPIValue(value[key]);
+            }
+            return cloned;
+        }
+        return value;
+    }
+    normalizeContentSchemas(content) {
+        if (!content) {
+            return content;
+        }
+        for (const key in content) {
+            if (content[key]?.schema) {
+                content[key].schema = this.formatType(content[key].schema);
+            }
+        }
+        return content;
+    }
+    normalizeOperationParameters(parameters) {
+        if (!Array.isArray(parameters)) {
+            return [];
+        }
+        return parameters.map(parameter => {
+            const normalized = this.cloneOpenAPIValue(parameter);
+            if (normalized?.schema) {
+                normalized.schema = this.formatType(normalized.schema);
+            }
+            if (normalized.content) {
+                normalized.content = this.normalizeContentSchemas(normalized.content);
+            }
+            return normalized;
+        });
+    }
+    normalizeOperationRequestBody(requestBody) {
+        if (!requestBody) {
+            return undefined;
+        }
+        const normalized = this.cloneOpenAPIValue(requestBody);
+        if (normalized.content) {
+            normalized.content = this.normalizeContentSchemas(normalized.content);
+        }
+        return normalized;
+    }
+    normalizeOperationResponse(response) {
+        const normalized = this.cloneOpenAPIValue(response);
+        if (normalized.schema) {
+            normalized.content = {
+                'application/json': {
+                    schema: this.formatType(normalized.schema),
+                },
+            };
+            delete normalized.schema;
+        }
+        else if (normalized.type) {
+            if (core_1.Types.isClass(normalized.type)) {
+                this.parseClzz(normalized.type);
+                if (normalized.isArray) {
+                    normalized.content = {
+                        'application/json': {
+                            schema: {
+                                type: 'array',
+                                items: {
+                                    $ref: '#/components/schemas/' + normalized.type.name,
+                                },
+                            },
+                        },
+                    };
+                }
+                else {
+                    normalized.content = {
+                        'application/json': {
+                            schema: {
+                                $ref: '#/components/schemas/' + normalized.type.name,
+                            },
+                        },
+                    };
+                }
+            }
+            else {
+                normalized.content = {
+                    'text/plain': {
+                        schema: {
+                            type: convertSchemaType(normalized.type),
+                        },
+                    },
+                };
+            }
+        }
+        else if (normalized.content) {
+            normalized.content = this.normalizeContentSchemas(normalized.content);
+        }
+        delete normalized.status;
+        delete normalized.type;
+        delete normalized.isArray;
+        delete normalized.format;
+        return normalized;
+    }
+    normalizeOperationResponses(responses) {
+        if (!responses) {
+            return undefined;
+        }
+        const normalizedResponses = this.cloneOpenAPIValue(responses);
+        for (const status in normalizedResponses) {
+            normalizedResponses[status] = this.normalizeOperationResponse(normalizedResponses[status]);
+        }
+        return normalizedResponses;
+    }
     getOperationId(controllerKey, webRouter) {
         return this.operationIdFactory(controllerKey, webRouter);
     }
@@ -772,6 +871,18 @@ let SwaggerExplorer = class SwaggerExplorer {
         for (const key in props) {
             props[key] = props[key][props[key].length - 1];
         }
+        if (this.swaggerConfig?.useValidationSchema) {
+            const inferredProps = this.inferValidationProperties(clzz);
+            for (const key of Object.keys(inferredProps)) {
+                if (!props[key]) {
+                    props[key] = inferredProps[key];
+                    continue;
+                }
+                const existingMeta = props[key].metadata || {};
+                const inferredMeta = inferredProps[key].metadata || {};
+                props[key].metadata = this.mergePropertyMetadata(existingMeta, inferredMeta);
+            }
+        }
         const tt = {
             type: 'object',
             properties: {},
@@ -843,6 +954,120 @@ let SwaggerExplorer = class SwaggerExplorer {
         // just for test
         return tt;
     }
+    mergePropertyMetadata(swaggerMetadata, inferredMetadata) {
+        const mergedMetadata = { ...swaggerMetadata };
+        const fillableKeys = [
+            'type',
+            'items',
+            'format',
+            'enum',
+            '$ref',
+            'pattern',
+            'default',
+        ];
+        for (const key of fillableKeys) {
+            if (mergedMetadata[key] === undefined &&
+                inferredMetadata[key] !== undefined) {
+                mergedMetadata[key] = inferredMetadata[key];
+            }
+        }
+        if (mergedMetadata.required === undefined &&
+            inferredMetadata.required !== undefined) {
+            mergedMetadata.required = inferredMetadata.required;
+        }
+        return mergedMetadata;
+    }
+    getValidationSchemaHelper() {
+        try {
+            const validationPkg = (0, core_1.safeRequire)('@midwayjs/validation');
+            const registry = validationPkg?.registry;
+            if (!registry?.getDefaultValidator) {
+                return;
+            }
+            return registry.getDefaultValidator()?.schemaHelper;
+        }
+        catch {
+            // When @midwayjs/validate and @midwayjs/validation are both installed in
+            // the same process, loading validation package may throw duplicated error
+            // group exceptions. Swagger should degrade gracefully in this case.
+            return;
+        }
+    }
+    inferValidationProperties(clzz) {
+        const ruleProps = core_1.MetadataManager.getPropertiesWithMetadata(VALIDATION_RULES_KEY, clzz) ||
+            {};
+        const hasRuleMetadata = Object.keys(ruleProps).length > 0;
+        const validateRuleProps = core_1.MetadataManager.getPropertiesWithMetadata(VALIDATE_RULES_KEY, clzz) || {};
+        const hasValidateRuleMetadata = Object.keys(validateRuleProps).length > 0;
+        const hasClassValidatorMetadata = this.hasClassValidatorMetadata(clzz);
+        if (!hasRuleMetadata &&
+            !hasClassValidatorMetadata &&
+            !hasValidateRuleMetadata) {
+            return {};
+        }
+        const inferredProps = {};
+        if (hasRuleMetadata || hasClassValidatorMetadata) {
+            const schemaHelper = this.getValidationSchemaHelper();
+            if (schemaHelper &&
+                typeof schemaHelper.getSwaggerPropertyKeys === 'function' &&
+                typeof schemaHelper.getSwaggerPropertyMetadata === 'function') {
+                const propertyKeys = schemaHelper.getSwaggerPropertyKeys(clzz) || [];
+                for (const key of propertyKeys) {
+                    const metadata = schemaHelper.getSwaggerPropertyMetadata(clzz, key);
+                    if (metadata) {
+                        inferredProps[key] = {
+                            metadata,
+                        };
+                    }
+                }
+            }
+        }
+        if (hasValidateRuleMetadata) {
+            const validateInferredProps = this.inferValidateProperties(clzz);
+            for (const [key, value] of Object.entries(validateInferredProps)) {
+                if (!inferredProps[key]) {
+                    inferredProps[key] = value;
+                    continue;
+                }
+                const mergedMetadata = this.mergePropertyMetadata(inferredProps[key].metadata || {}, value.metadata || {});
+                inferredProps[key] = {
+                    metadata: mergedMetadata,
+                };
+            }
+        }
+        return inferredProps;
+    }
+    inferValidateProperties(clzz) {
+        const inferredProps = {};
+        const ruleProps = core_1.MetadataManager.getPropertiesWithMetadata(VALIDATE_RULES_KEY, clzz) || {};
+        for (const key of Object.keys(ruleProps)) {
+            let schema = ruleProps[key];
+            if (typeof schema === 'function') {
+                schema = schema();
+            }
+            const metadata = inferJoiPropertyMetadata(schema);
+            if (metadata) {
+                inferredProps[key] = {
+                    metadata,
+                };
+            }
+        }
+        return inferredProps;
+    }
+    hasClassValidatorMetadata(clzz) {
+        try {
+            const classValidator = (0, core_1.safeRequire)('class-validator-multi-lang-lite');
+            const storage = classValidator?.getMetadataStorage?.();
+            if (!storage?.getTargetValidationMetadatas) {
+                return false;
+            }
+            const metadatas = storage.getTargetValidationMetadatas(clzz, '', false, false) || [];
+            return metadatas.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * 授权验证
      * @param opts
@@ -960,6 +1185,47 @@ function convertSchemaType(value) {
             return 'object';
     }
 }
+function inferJoiPropertyMetadata(schema) {
+    if (!schema || typeof schema.describe !== 'function') {
+        return null;
+    }
+    const desc = schema.describe();
+    if (!desc || typeof desc !== 'object') {
+        return null;
+    }
+    const typeMap = {
+        string: 'string',
+        number: 'number',
+        boolean: 'boolean',
+        array: 'array',
+        date: 'string',
+        object: 'object',
+    };
+    const metadata = {
+        type: typeMap[desc.type] || 'object',
+    };
+    if (desc?.flags?.presence === 'required') {
+        metadata.required = true;
+    }
+    else if (desc?.flags?.presence === 'optional' || !desc?.flags?.presence) {
+        metadata.required = false;
+    }
+    if (desc.type === 'array' && Array.isArray(desc.items)) {
+        metadata.items = {
+            type: typeMap[desc.items[0]?.type] || 'object',
+        };
+    }
+    if (desc.type === 'date') {
+        metadata.format = 'date-time';
+    }
+    if (Array.isArray(desc.allow)) {
+        const enumValues = desc.allow.filter(item => item !== '' && item !== null && item !== undefined);
+        if (enumValues.length > 0) {
+            metadata.enum = enumValues;
+        }
+    }
+    return metadata;
+}
 function getNotEmptyValue(...args) {
     for (const arg of args) {
         if (arg) {

package/dist/ui/render.js

@@ -23,8 +23,9 @@ function renderSwaggerUIDist(swaggerConfig, swaggerExplorer) {
     function replaceInfo(content) {
         let str = `location.href.replace('${swaggerConfig.swaggerPath}/index.html', '${swaggerConfig.swaggerPath}/index.json'),\n validatorUrl: null,`;
         if (swaggerConfig.displayOptions) {
-            Object.keys(swaggerConfig.displayOptions).forEach(key => {
-                str += `\n${key}: ${swaggerConfig.displayOptions[key]},`;
+            Object.entries(swaggerConfig.displayOptions).forEach(([key, value]) => {
+                const variable = typeof value === 'string' ? `'${value}'` : value;
+                str += `\n${key}: ${variable},`;
             });
         }
         return content.replace('"https://petstore.swagger.io/v2/swagger.json",', str);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midwayjs/swagger",
-  "version": "4.0.0-beta.8",
+  "version": "4.0.0",
   "description": "Midway Component for Swagger API Documentation",
   "main": "dist/index.js",
   "typings": "index.d.ts",
@@ -12,10 +12,10 @@
   ],
   "devDependencies": {
     "@apidevtools/swagger-parser": "11.0.1",
-    "@midwayjs/core": "^4.0.0-beta.8",
-    "@midwayjs/koa": "^4.0.0-beta.8",
-    "@midwayjs/mock": "^4.0.0-beta.8",
-    "@midwayjs/validate": "^4.0.0-beta.8",
+    "@midwayjs/core": "^4.0.0",
+    "@midwayjs/koa": "^4.0.0",
+    "@midwayjs/mock": "^4.0.0",
+    "@midwayjs/validate": "^4.0.0",
     "swagger-ui-dist": "5.18.3"
   },
   "author": "Kurten Chan <chinkurten@gmail.com>",
@@ -30,5 +30,5 @@
     "type": "git",
     "url": "https://github.com/midwayjs/midway.git"
   },
-  "gitHead": "355e55949fdd132b0bdcb4830222a0a027e92ded"
+  "gitHead": "014f32c23ebc1d5ac21777c76be2fd373ce992d8"
 }