Spring Doc OpenAPI3.0 抛弃SpringFox拥抱SpringDoc

Myth丶恋晨 2024-03-22 08:54 75阅读 0赞

## Spring Doc ##

### 1 简介 ###

SpringDoc是SpringBoot 的API文档工具。官网：[https://springdoc.org/][https_springdoc.org]

在使用SpringBoot 2.6以前去创建API文档工具一般会采用`SpringFox`提供的Swagger库，但是由于SpringBoot版本的不断升级和SpringFox摆烂不更新，导致了SpringBoot2.6之后的项目无法使用SpringFox去生成API文档，或者可以使用但是有很多的bug。

SpringDoc是一款可以结合SpringBoot使用API文档生成工具，基于`OpenAPI 3`，而且项目维护和社区都在不断更新，不仅支持`SpringMVC`，而且还支持`Spring WebFlux`项目。

下图为SpringDoc的架构图的总体概述。  
![在这里插入图片描述][8f9d9ddc5fe54fa891244d82f9699462.jpeg_pic_center]

### 2 基本使用 ###

#### 2.1 新建项目并导入maven ####

<dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.7.0</version>
    </dependency>

#### 2.2 使用注解标记接口 ####

##### 2.2.1 常用注解 #####

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Tag</td> 
   <td>标记在接口类上，用来设置 Controller 的名称和描述</td> 
  </tr> 
  <tr> 
   <td>@Parameter/@Parameters</td> 
   <td>用来设置请求参数的描述</td> 
  </tr> 
  <tr> 
   <td>@Operation</td> 
   <td>对接口方法的描述，可以设置接口的名称</td> 
  </tr> 
  <tr> 
   <td>@ApiResponse/@ApiResponses</td> 
   <td>用来配置响应</td> 
  </tr> 
  <tr> 
   <td>@Schema</td> 
   <td>标记在模型（model）类上或类的属性上，进行标注解释。</td> 
  </tr> 
 </tbody> 
</table>

##### 2.2.2 测试Controler Demo #####

**TestController**

package org.example.controller.test;
    /**
     * 省略import
     */
    @Tag(name = "测试接口", description = "定义测试接口")
    @RestController
    @RequestMapping("/test")
    public class TestController {
        
        @Operation(summary = "get测试接口", description = "返回id")
        @Parameter(name = "id", description = "参数ID", example = "123456")
        @ApiResponse(responseCode = "403", description = "无权限")
        @GetMapping("/get")
        public Map<String, Object> get(@Parameter(description = "id") String id) {
        
            Map<String, Object> res = new HashMap<>(1);
            res.put("id", id);
            return res;
        }
    }

**UserController**

package org.example.controller.user;
    /**
     * 省略import
     */
    @Tag(name = "用户接口", description = "定义用户接口")
    @RestController
    @RequestMapping("/user")
    public class UserController {
        
        @Operation(summary = "post测试接口", description = "返回username")
        @Parameter(name = "username", description = "参数username", example = "username")
        @ApiResponse(responseCode = "403", description = "无权限")
        @PostMapping("/post")
        public Map<String, Object> get(@Parameter(description = "用户名") String username) {
        
            Map<String, Object> res = new HashMap<>(1);
            res.put("username", username);
            return res;
        }
    }

#### 2.3 编写SpringDocConfig ####

##### 2.3.1 常用springdoc的配置 #####

package org.example.config;
    
    import io.swagger.v3.oas.models.Components;
    import io.swagger.v3.oas.models.ExternalDocumentation;
    import io.swagger.v3.oas.models.OpenAPI;
    import io.swagger.v3.oas.models.info.Contact;
    import io.swagger.v3.oas.models.info.Info;
    import io.swagger.v3.oas.models.info.License;
    import io.swagger.v3.oas.models.security.SecurityRequirement;
    import io.swagger.v3.oas.models.security.SecurityScheme;
    import org.springdoc.core.GroupedOpenApi;
    import org.springdoc.core.customizers.OpenApiCustomiser;
    import org.springdoc.core.customizers.OperationCustomizer;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    
    /**
     * @author zhong
     */
    @Configuration
    public class SpringDocConfig {
        
    
        @Bean
        public OpenAPI defaultOpenAPI() {
        
    //        return new OpenAPI()
    //                .info(info())
    //                .externalDocs(documentation())
    //                .components(new Components().addSecuritySchemes("Authorization", new SecurityScheme().name("认证").type(SecurityScheme.Type.HTTP)
    //                        .description("JWT认证").scheme("bearer").bearerFormat("JWT")));
    
    
            return new OpenAPI().
                    info(info())
                    .externalDocs(documentation());
        }
    
        public Info info() {
        
            return new Info()
                    .title("SpringDoc OpenApi")
                    .version("V1.0.0")
                    .description("测试spring doc open api")
                    .license(new License().name("许可证名称").url("许可证地址"))
                    .contact(new Contact().name("联系人").url("联想人链接"))
                    .summary("概要");
        }
    
        public ExternalDocumentation documentation() {
        
            return new ExternalDocumentation().description("文档描述").url("文档地址");
        }
    
        @Bean
        public GroupedOpenApi testApi() {
        
            return GroupedOpenApi.builder()
                    .displayName("测试接口")
                    .group("test")
                    .packagesToScan("org.example.controller.test")
                    .build();
        }
    
        @Bean
        public GroupedOpenApi userApi() {
        
            return GroupedOpenApi.builder()
                    .displayName("用户接口")
                    .group("user")
                    .packagesToScan("org.example.controller.user")
                    .addOpenApiCustomiser(openApiCustomiser())
                    .addOperationCustomizer(operationCustomizer())
                    .build();
        }
    
        public OpenApiCustomiser openApiCustomiser() {
        
            return api ->
                    api.components(new Components()
                            .addSecuritySchemes("Authorization", new SecurityScheme().name("认证").type(SecurityScheme.Type.HTTP)
                                    .description("JWT认证").scheme("bearer").bearerFormat("JWT"))
                    );
        }
    
        public OperationCustomizer operationCustomizer() {
        
            return (operation, handlerMethod) -> {
        
                operation.addSecurityItem(new SecurityRequirement().addList("Authorization"));
                return operation;
            };
        }
    }

##### 2.3.2 关于接口鉴权问题（jwt方式） #####

如以上配置所示，user接口设置了鉴权设置

**对一个分组的接口添加鉴权的方式**

@Bean
        public GroupedOpenApi userApi() {
        
            return GroupedOpenApi.builder()
                    .displayName("用户接口")
                    .group("user")
                    .packagesToScan("org.example.controller.user")
                    .addOpenApiCustomiser(openApiCustomiser())
                    .addOperationCustomizer(operationCustomizer())
                    .build();
    }
    public OpenApiCustomiser openApiCustomiser() {
        
        return api ->
                api.components(new Components()
                        .addSecuritySchemes("Authorization", new SecurityScheme().name("认证").type(SecurityScheme.Type.HTTP)
                                .description("JWT认证").scheme("bearer").bearerFormat("JWT"))
                );
    }
    
    public OperationCustomizer operationCustomizer() {
        
        return (operation, handlerMethod) -> {
        
            operation.addSecurityItem(new SecurityRequirement().addList("Authorization"));
            return operation;
        };
    }

**如果嫌麻烦，可以设置全局设置**

例如配置代码注释的部分添加全局配置

@Bean
        public OpenAPI defaultOpenAPI() {
        
            return new OpenAPI()
                    .info(info())
                    .externalDocs(documentation())
                    .components(new Components().addSecuritySchemes("Authorization", new SecurityScheme().name("认证").type(SecurityScheme.Type.HTTP)
                            .description("JWT认证").scheme("bearer").bearerFormat("JWT")));
    
        }

#### 2.4 启动效果 ####

访问[http://localhost:8080/swagger-ui/index.html][http_localhost_8080_swagger-ui_index.html]

![在这里插入图片描述][9be78861828647d2ab36b74d3a9d4def.png_pic_center]

#### 2.5 一些application的配置说明 ####

##### 2.5.1 springdoc-openapi 核心属性 #####

官方链接：[https://springdoc.org/\#springdoc-openapi-core-properties][https_springdoc.org_springdoc-openapi-core-properties]

<table> 
 <thead> 
  <tr> 
   <th align="left">参数名称</th> 
   <th align="left">默认值</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">springdoc.api-docs.path</td> 
   <td align="left"><code>/v3/api-docs</code></td> 
   <td align="left"><code>String</code>, 用于 Json 格式的 OpenAPI 文档的自定义路径。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.api-docs.enabled</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用 springdoc-openapi 端点（默认为 /v3/api-docs）。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.packages-to-scan</td> 
   <td align="left"><code>*</code></td> 
   <td align="left"><code>List of Strings</code>.要扫描的包列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.paths-to-match</td> 
   <td align="left"><code>/*</code></td> 
   <td align="left"><code>List of Strings</code>.要匹配的路径列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.produces-to-match</td> 
   <td align="left"><code>/*</code></td> 
   <td align="left"><code>List of Strings</code>.The list of produces mediaTypes to match (逗号分隔)</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.headers-to-match</td> 
   <td align="left"><code>/*</code></td> 
   <td align="left"><code>List of Strings</code>.要匹配的标题列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.consumes-to-match</td> 
   <td align="left"><code>/*</code></td> 
   <td align="left"><code>List of Strings</code>.要匹配的消耗媒体类型列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.paths-to-exclude</td> 
   <td align="left"></td> 
   <td align="left"><code>List of Strings</code>.要排除的路径列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.packages-to-exclude</td> 
   <td align="left"></td> 
   <td align="left"><code>List of Strings</code>.要排除的包列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.default-consumes-media-type</td> 
   <td align="left"><code>application/json</code></td> 
   <td align="left"><code>String</code>. 默认使用媒体类型。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.default-produces-media-type</td> 
   <td align="left"><code>**/**</code></td> 
   <td align="left"><code>String</code>.默认产生媒体类型。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.cache.disabled</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 禁用计算 OpenAPI 的 springdoc-openapi 缓存。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.show-actuator</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 显示执行器端点。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.auto-tag-class</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用 springdoc-openapi 自动标签。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.model-and-view-allowed</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 允许带有 ModelAndView 返回的 RestControllers 出现在 OpenAPI 描述中。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.override-with-generic-response</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 当为 true 时，自动将 @ControllerAdvice 响应添加到所有生成的响应中。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.api-docs.groups.enabled</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用 springdoc-openapi 组。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].group</td> 
   <td align="left"></td> 
   <td align="left"><code>String</code>.群名</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].display-name</td> 
   <td align="left"></td> 
   <td align="left"><code>String</code>.组的显示名称。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].packages-to-scan</td> 
   <td align="left"><code>*</code></td> 
   <td align="left"><code>List of Strings</code>.要扫描组的包列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].paths-to-match</td> 
   <td align="left"><code>/*</code></td> 
   <td align="left"><code>List of Strings</code>.组匹配的路径列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].paths-to-exclude</td> 
   <td align="left">``</td> 
   <td align="left"><code>List of Strings</code>.要为组排除的路径列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].packages-to-exclude</td> 
   <td align="left"></td> 
   <td align="left"><code>List of Strings</code>.要排除的包列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].produces-to-match</td> 
   <td align="left"><code>/*</code></td> 
   <td align="left"><code>List of Strings</code>.The list of produces mediaTypes to match (逗号分隔)</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].consumes-to-match</td> 
   <td align="left"><code>/*</code></td> 
   <td align="left"><code>List of Strings</code>.要匹配的消耗媒体类型列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.group-configs[0].headers-to-match</td> 
   <td align="left"><code>/*</code></td> 
   <td align="left"><code>List of Strings</code>.要匹配的标题列表（逗号分隔）</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.webjars.prefix</td> 
   <td align="left"><code>/webjars</code></td> 
   <td align="left"><code>String</code>, 把swagger-ui的URL可见的webjars前缀换成spring-webflux。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.api-docs.resolve-schema-properties</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 在@Schema 上启用属性解析器（名称、标题和描述）。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.remove-broken-reference-definitions</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用删除损坏的引用定义。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.writer-with-default-pretty-printer</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 启用 OpenApi 规范的漂亮打印。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.model-converters.deprecating-converter.enabled</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用弃用模型转换器。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.model-converters.polymorphic-converter.enabled</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用多态模型转换器。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.model-converters.pageable-converter.enabled</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用可分页模型转换器。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.model-converters.sort-converter.enabled</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用排序转换器。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.use-fqn</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 启用完全限定名称。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.show-endpoint</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 使 spring security 登录端点可见。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.pre-loading-enabled</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 预加载设置以在应用程序启动时加载 OpenAPI。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.writer-with-order-by-keys</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 启用确定性/字母顺序。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.use-management-port</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 在执行器管理端口上公开 swagger-ui。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.disable-i18n</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 使用 i18n 禁用自动翻译。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.show-spring-cloud-functions</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 显示 spring-cloud-function Web 端点。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.api-docs.version</td> 
   <td align="left"><code>openapi_3_0</code></td> 
   <td align="left"><code>String</code>. 选择<code>OpenAPI 3.0</code>或<code>OpenAPI 3.1</code>（使用值<code>OPENAPI_3_1</code>）。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.default-flat-param-object</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 默认展平参数。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.default-support-form-data</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 指定api接受表单数据时默认设置参数为表单数据。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.nullable-request-parameter-enabled</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 在 Kotlin 中默认启用对可空请求参数的支持。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.show-oauth2-endpoints</td> 
   <td align="left"><code>false</code></td> 
   <td align="left"><code>Boolean</code>. 使 spring security oauth2-endpoint 可见。</td> 
  </tr> 
 </tbody> 
</table>

##### 2.5.2 swagger-ui核心属性 #####

官方链接[https://springdoc.org/\#swagger-ui-properties][https_springdoc.org_swagger-ui-properties]

<table> 
 <thead> 
  <tr> 
   <th align="left">参数名称</th> 
   <th align="left">默认值</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">springdoc.swagger-ui.path</td> 
   <td align="left"><code>/swagger-ui.html</code></td> 
   <td align="left"><code>String</code>, 用于 swagger-ui HTML 文档的自定义路径。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.swagger-ui.enabled</td> 
   <td align="left"><code>true</code></td> 
   <td align="left"><code>Boolean</code>. 禁用 swagger-ui 端点（默认为 /swagger-ui.html）。</td> 
  </tr> 
  <tr> 
   <td align="left">springdoc.swagger-ui.configUrl</td> 
   <td align="left"><code>/v3/api-docs/swagger-config</code></td> 
   <td align="left"><code>String</code>. 从中获取外部配置文档的 URL。</td> 
  </tr> 
 </tbody> 
</table>

### 2 从SpringFox迁移 ###

*  删除 springfox 和 swagger 2 依赖项。添加`springdoc-openapi-ui`依赖项。

<dependency>
          <groupId>org.springdoc</groupId>
          <artifactId>springdoc-openapi-ui</artifactId>
          <version>1.7.0</version>
       </dependency>

*  用 swagger 3 注释替换 swagger 2 注释（它已经包含在`springdoc-openapi-ui`依赖项中）。swagger 3 注释的包是`io.swagger.v3.oas.annotations`.
    
     *  `@Api`→`@Tag`
     *  `@ApiIgnore`→`@Parameter(hidden = true)`或`@Operation(hidden = true)`或`@Hidden`
     *  `@ApiImplicitParam`→`@Parameter`
     *  `@ApiImplicitParams`→`@Parameters`
     *  `@ApiModel`→`@Schema`
     *  `@ApiModelProperty(hidden = true)`→`@Schema(accessMode = READ_ONLY)`
     *  `@ApiModelProperty`→`@Schema`
     *  `@ApiOperation(value = "foo", notes = "bar")`→`@Operation(summary = "foo", description = "bar")`
     *  `@ApiParam`→`@Parameter`
     *  `@ApiResponse(code = 404, message = "foo")`→`@ApiResponse(responseCode = "404", description = "foo")`
 *  如果您使用一个对象来捕获多个请求查询参数，请注释该方法参数`@ParameterObject`
 *  此步骤是可选的：仅当您有**多个** `Docket`beans 时才用`GroupedOpenApi`beans 替换它们。

前：

@Bean
      public Docket publicApi() {
        
          return new Docket(DocumentationType.SWAGGER_2)
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
                  .paths(PathSelectors.regex("/public.*"))
                  .build()
                  .groupName("springshop-public")
                  .apiInfo(apiInfo());
      }
    
      @Bean
      public Docket adminApi() {
        
          return new Docket(DocumentationType.SWAGGER_2)
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
                  .paths(PathSelectors.regex("/admin.*"))
                  .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
                  .build()
                  .groupName("springshop-admin")
                  .apiInfo(apiInfo());
      }

现在：

@Bean
      public GroupedOpenApi publicApi() {
        
          return GroupedOpenApi.builder()
                  .group("springshop-public")
                  .pathsToMatch("/public/**")
                  .build();
      }
      @Bean
      public GroupedOpenApi adminApi() {
        
          return GroupedOpenApi.builder()
                  .group("springshop-admin")
                  .pathsToMatch("/admin/**")
                  .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
                  .build();
      }

如果你**只有一个** `Docket` - 删除它并添加属性到你的`application.properties`：

springdoc.packagesToScan=package1, package2
    springdoc.pathsToMatch=/v1, /api/balance/**

*  添加`OpenAPI`类型的bean。参见示例：

@Bean
      public OpenAPI springShopOpenAPI() {
        
          return new OpenAPI()
                  .info(new Info().title("SpringShop API")
                  .description("Spring shop sample application")
                  .version("v0.0.1")
                  .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                  .externalDocs(new ExternalDocumentation()
                  .description("SpringShop Wiki Documentation")
                  .url("https://springshop.wiki.github.org/docs"));
      }

### 3 使用 knife4j美化 ###

![在这里插入图片描述][3187422207ba40b9892e9e8e5c2b58f5.png_pic_center]

#### 3.1 使用方法 ####

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案。

官网：[https://doc.xiaominfo.com/][https_doc.xiaominfo.com]

首先，引用Knife4j的starter,Maven坐标如下：

<dependency>
    	<groupId>com.github.xiaoymin</groupId>
    	<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    	<version>4.1.0</version>
    </dependency>

然后删除之前的`springdoc-openapi-ui`

![在这里插入图片描述][29fd8c2f09bf4b5da95382381e48273e.png_pic_center]

#### 3.2 常用配置项 ####

官方说明地址：[https://doc.xiaominfo.com/docs/features/enhance][https_doc.xiaominfo.com_docs_features_enhance]

## knife4j的增强配置，不需要增强可以不配
    knife4j:
      enable: true
      setting:
        language: zh_cn
        enable-home-custom: true
        home-custom-path: classpath:markdown/api-home.md
        enable-footer-custom: true
        footer-custom-content: 系统文档

[https_springdoc.org]: https://springdoc.org/
[8f9d9ddc5fe54fa891244d82f9699462.jpeg_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/22/67c48f5a54514ffebdf64c0b4db8cd02.png
[http_localhost_8080_swagger-ui_index.html]: http://localhost:8080/swagger-ui/index.html#/
[9be78861828647d2ab36b74d3a9d4def.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/22/5c2cfe39d9984aa88e7c4691287c017c.png
[https_springdoc.org_springdoc-openapi-core-properties]: https://springdoc.org/#springdoc-openapi-core-properties
[https_springdoc.org_swagger-ui-properties]: https://springdoc.org/#swagger-ui-properties
[3187422207ba40b9892e9e8e5c2b58f5.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/22/f9eb301183c5417993a49fdd72ce5f42.png
[https_doc.xiaominfo.com]: https://doc.xiaominfo.com/
[29fd8c2f09bf4b5da95382381e48273e.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/22/db8679d3bd3f4f43820e5e5c8f2973cf.png
[https_doc.xiaominfo.com_docs_features_enhance]: https://doc.xiaominfo.com/docs/features/enhance