feat: add display options and fix array bug (#2103)

midwayjs · Jul 10, 2022 · 4f8e06d · 4f8e06d
1 parent 48ea090
commit 4f8e06d
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 5 deletions.
diff --git a/packages/swagger/src/interfaces/index.ts b/packages/swagger/src/interfaces/index.ts
@@ -393,4 +393,23 @@ export interface SwaggerOptions {
    * 可以使用 1-xxx、2-xxx、3-xxx 来定义 tag
    */
   tagSortable?: boolean;
+  /**
+   * UI 展示中需要用到的配置
+   * 可以参考 https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#display
+   */
+  displayOptions?: {
+    deepLinking?: boolean;
+    displayOperationId?: boolean;
+    defaultModelsExpandDepth?: number;
+    defaultModelExpandDepth?: number;
+    defaultModelRendering?: 'example' | 'model';
+    displayRequestDuration?: boolean;
+    docExpansion?: 'list' | 'full' | 'none';
+    filter?: boolean | string;
+    maxDisplayedTags?: number;
+    showExtensions?: boolean;
+    showCommonExtensions?: boolean;
+    useUnsafeMarkdown?: boolean;
+    tryItOutEnabled?: boolean;
+  };
 }
diff --git a/packages/swagger/src/swaggerExplorer.ts b/packages/swagger/src/swaggerExplorer.ts
@@ -520,7 +520,7 @@ export class SwaggerExplorer {
         if (param.in === 'query') {
           p.allowEmptyValue = param.allowEmptyValue || false;
         }
-        if (param.example) {
+        if (typeof param.example !== undefined) {
           p.example = param.example;
         }
         if (param.examples) {
@@ -559,13 +559,22 @@ export class SwaggerExplorer {
             }
 
             if (param.isArray) {
+              let ref;
+              if (p?.schema?.$ref) {
+                ref = p.schema.$ref;
+              }
+
               p.schema = {
                 type: 'array',
                 items: {
-                  type: p?.schema?.$ref ?? convertSchemaType(param.type),
                   format: param.format,
                 },
               };
+              if (ref) {
+                p.schema.items.$ref = ref;
+              } else {
+                p.schema.items.type = convertSchemaType(param.type);
+              }
             } else {
               if (!p.schema) {
                 p.schema = {
@@ -622,7 +631,7 @@ export class SwaggerExplorer {
       Object.keys(props).forEach(key => {
         const metadata = props[key].metadata;
 
-        if (metadata?.example) {
+        if (typeof metadata?.example !== undefined) {
           if (!tt.example) {
             tt.example = {};
           }

diff --git a/packages/swagger/src/swaggerMiddleware.ts b/packages/swagger/src/swaggerMiddleware.ts
@@ -16,6 +16,7 @@ import {
 } from '@midwayjs/decorator';
 import { readFileSync } from 'fs';
 import { join, extname } from 'path';
+import type { SwaggerOptions } from './interfaces';
 import { SwaggerExplorer } from './swaggerExplorer';
 
 @Provide()
@@ -24,7 +25,7 @@ export class SwaggerMiddleware
   implements IMiddleware<IMidwayContext, NextFunction, unknown>
 {
   @Config('swagger')
-  private swaggerConfig: any;
+  private swaggerConfig: SwaggerOptions;
 
   private swaggerUiAssetPath: string;
 
@@ -126,9 +127,15 @@ export class SwaggerMiddleware
   }
 
   replaceInfo(content: string): string {
+    let str = `location.href.replace('${this.swaggerConfig.swaggerPath}/index.html', '${this.swaggerConfig.swaggerPath}/index.json'),\n validatorUrl: null,`;
+    if (this.swaggerConfig.displayOptions) {
+      Object.keys(this.swaggerConfig.displayOptions).forEach(key => {
+        str += `\n${key}: ${this.swaggerConfig.displayOptions[key]},`;
+      });
+    }
     return content.replace(
       '"https://petstore.swagger.io/v2/swagger.json",',
-      `location.href.replace('${this.swaggerConfig.swaggerPath}/index.html', '${this.swaggerConfig.swaggerPath}/index.json'),\n validatorUrl: null,`
+      str
     );
   }
 

diff --git a/site/docs/extensions/swagger.md b/site/docs/extensions/swagger.md
@@ -656,6 +656,25 @@ export interface SwaggerOptions {
    * 可以使用 1-xxx、2-xxx、3-xxx 来定义 tag
    */
   tagSortable?: boolean;
+  /**
+   * UI 展示中需要用到的配置
+   * 可以参考 https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#display
+   */
+  displayOptions?: {
+    deepLinking?: boolean;
+    displayOperationId?: boolean;
+    defaultModelsExpandDepth?: number;
+    defaultModelExpandDepth?: number;
+    defaultModelRendering?: 'example' | 'model';
+    displayRequestDuration?: boolean;
+    docExpansion?: 'list' | 'full' | 'none';
+    filter?: boolean | string;
+    maxDisplayedTags?: number;
+    showExtensions?: boolean;
+    showCommonExtensions?: boolean;
+    useUnsafeMarkdown?: boolean;
+    tryItOutEnabled?: boolean;
+  };
 }
 /**
  * 继承自 https://swagger.io/specification/#security-scheme-object