Java21 + SpringBoot3 整合 SpringDoc OpenApi，探索 API 文档自动生成之旅

一、OpenAPI、Swagger、Springfox 和 SpringDoc 的前世今生

1. OpenAPI：API 标准

OpenAPI 是一种用于 RESTful API 的标准，它定义了一套规范，用于描述 API 的端点、参数、响应等信息。OpenAPI 文档可以帮助开发人员快速理解 API 的功能和使用方法，从而提高 API 的可用性。

2. Swagger：API 文档生成工具鼻祖

Swagger 是一款流行的 API 文档生成工具，它基于 OpenAPI 标准，可以自动生成美观且实用的 API 文档。Swagger 具有丰富的功能，可以生成多种格式的文档，还可以与多种编程语言集成。

3. Springfox：SpringBoot 专属的 Swagger 工具包

Springfox 是 SpringBoot 框架专用的 Swagger 工具包，它简化了在 SpringBoot 项目中使用 Swagger 的过程。Springfox 集成了 Swagger 的全部功能，并且提供了许多 SpringBoot 特有的特性，例如与 Spring Security 的集成。

4. SpringDoc：新一代 SpringBoot API 文档生成工具

SpringDoc 是 SpringBoot 框架的新一代 API 文档生成工具，它继承了 Springfox 的优点，同时又进行了许多改进。SpringDoc 具有更简洁、更易用的 API，并且提供了更多强大的功能，例如对 OpenAPI 3.0 标准的支持。

二、Java21 + SpringBoot3 整合 SpringDoc OpenApi 实战

1. 导入 SpringDoc OpenApi 依赖

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

2. 配置 SpringDoc OpenApi

@Configuration
public class OpenApiConfig {

  @Bean
  public OpenApiCustomiser customizeOpenApi() {
    return openApi -> openApi.info(new Info().title("Your API Title")
        .description("Your API Description").version("1.0"));
  }

}

3. 启动 SpringBoot 应用

public class Application {

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }

}

三、使用 SpringDoc OpenApi 生成在线接口文档

1. 访问在线接口文档

在浏览器中输入 http://localhost:8080/swagger-ui.html，即可访问在线接口文档。

2. 查看 API 文档

在线接口文档包含了 API 的所有端点、参数、响应等信息，您可以通过左侧的导航栏选择不同的端点查看详细的文档。

四、在 SpringDoc OpenApi 中实现 SpringSecurity 和 JWT 认证

1. 配置 SpringSecurity

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {

  @Override
  protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .antMatchers("/api/**").authenticated()
        .and()
        .oauth2ResourceServer()
        .jwt();
  }

}

2. 配置 SpringDoc OpenApi

@Configuration
public class OpenApiConfig {

  @Bean
  public OpenApiCustomiser customizeOpenApi() {
    return openApi -> openApi.info(new Info().title("Your API Title")
        .description("Your API Description").version("1.0"))
        .securityRequirements(Collections.singletonList(new SecurityRequirement()
            .addList("JWT", Collections.emptyList())));
  }

}

五、总结

本文详细介绍了 Java21 + SpringBoot3 整合 SpringDoc OpenApi 的过程，并讲解了如何在 SpringDoc OpenApi 中实现 SpringSecurity 和 JWT 认证。通过使用 SpringDoc OpenApi，您可以轻松生成美观且实用的在线接口文档，从而提高 API 的可用性。同时，SpringDoc OpenApi 还支持 SpringSecurity 和 JWT 认证，为您提供更加安全的 API 文档访问体验。