Spring Doc OpenAPI3.0 抛弃SpringFox拥抱SpringDoc

Spring Doc

1 简介

SpringDoc是SpringBoot 的API文档工具。官网：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的架构图的总体概述。

2 基本使用

2.1 新建项目并导入maven

<dependency>    <groupId>org.springdocgroupId>    <artifactId>springdoc-openapi-uiartifactId>    <version>1.7.0version>dependency>

2.2 使用注解标记接口

2.2.1 常用注解

2.2.2 测试Controler Demo

TestController

package org.example.controller.test;@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;@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;@Configurationpublic 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

2.5 一些application的配置说明

2.5.1 springdoc-openapi 核心属性

官方链接：https://springdoc.org/#springdoc-openapi-core-properties

2.5.2 swagger-ui核心属性

官方链接https://springdoc.org/#swagger-ui-properties

2 从SpringFox迁移

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

   <dependency>      <groupId>org.springdocgroupId>      <artifactId>springdoc-openapi-uiartifactId>      <version>1.7.0version>   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
• 此步骤是可选的：仅当您有多个 Docketbeans 时才用GroupedOpenApibeans 替换它们。

前：

  @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, package2springdoc.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美化

3.1 使用方法

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

官网：https://doc.xiaominfo.com/

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

<dependency><groupId>com.github.xiaoymingroupId><artifactId>knife4j-openapi3-spring-boot-starterartifactId><version>4.1.0version>dependency>

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

3.2 常用配置项

官方说明地址：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://blog.csdn.net/zhongjianboy/article/details/130362180