什么是 SpringDoc-OpenAPI？

SpringDoc是另外一个Spring的库，能生成OpenAPI3格式的API描述文件。SpringDoc-OpenAPI通过运行时检测应用程序来根据Spring的配置、类结构和各种注解推断API语义来自动生成JSON、YAML和HTML格式的API文档。

下面通过示例代码说明如何使用SpringDoc。

• 添加SpringCoc-OpenAPI依赖

<!-- provides springdoc-openapi-ui -->
<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.0.2</version>
</dependency>
<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
   <version>2.0.2</version>
 </dependency>

• 使用swagger 3 的注解（已包含在springdoc-openapi-ui依赖项中）
• 添加配置

@Bean
 public OpenAPI springOpenAPI() {
  return new OpenAPI()
    .info(new Info().title("Micro service").description("APIs for Test Console service").version("1.0")
      .license(new License().name("Dev Team").url("https://github.com")))
    .externalDocs(new ExternalDocumentation().description("Test Documentation").url("https://github.com"));
 }

需要分组的话使用GroupedOpenApi

@Bean 
 public GroupedOpenApi publicApi () { 
  return GroupedOpenApi.builder().group( "test-api" ).pathsToMatch( "/api/**" ).build(); 
}

• 授权

@Bean
 public OpenAPI customizeOpenAPI() {
  final String securitySchemeName = "bearerAuth";
  return new OpenAPI()
    .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
          .components(
              new Components()
                  .addSecuritySchemes(securitySchemeName,
                      new SecurityScheme()
                          .name(securitySchemeName)
                          .type(SecurityScheme.Type.HTTP)
                          .scheme("bearer")
                          .bearerFormat("JWT")
                  )
          );
 }

• 参数列表重复项处理

在 Spring Doc open-api 中，必须手动处理参数列表中的重复项，以便标头不会出现两次。出现此问题的缘由是 open-api 扫描控制器类，将请求标头添加到参数列表中并在 /swagger-ui.html 中显示。当我们添加与全局标题一样的标题时，由于它是一个列表，因此它会出现两次。在 swagger 中是自动处理的，但在 open-api 中我们必须手动处理。

public static final String TEST_HEADER = "test-header";
 
 @Bean
 public GroupedOpenApi publicApi() {
  return GroupedOpenApi.builder().group("test-api").pathsToMatch("/api/**").build();
 }
 
 @Bean
 public OperationCustomizer customGlobalHeaders() {

  return (Operation operation, HandlerMethod handlerMethod) -> {
   Optional<List<Parameter>> isParameterPresent = Optional.ofNullable(operation.getParameters());
   Boolean isTestHeaderPresent = Boolean.FALSE;
   if (isParameterPresent.isPresent()) {
    isTestHeaderPresent = isParameterPresent.get().stream()
      .anyMatch(param -> param.getName().equalsIgnoreCase(TEST_HEADER));
   }
   if (Boolean.FALSE.equals(isTestHeaderPresent)) {
    Parameter remoteUser = new Parameter().in(ParameterIn.HEADER.toString()).schema(new StringSchema())
      .name(TEST_HEADER).description("Test Header").required(true);
    operation.addParametersItem(remoteUser);
   }
   return operation;
  };
 }

• 反向代理配置

如果项目是部署在反向代理后面的，列如Spring Cloud Gateway则必须在applicatin.yml文件中添加以下配置：

server.forward-headers-strategy=framework

• 访问

在浏览器中输入 http://localhost:8080/swagger-ui/index.html就可以访问API文档了。

SpringDoc默认使用Swagger2的Url格式，可以在application.yml配置文件中改为Swagger3的格式。

springdoc:
  swagger-ui:
   path: /swagger-ui