12.SpringDoc OpenAPI 功能介绍(用于生成API接口文档)

12.SpringDoc OpenAPI 功能介绍(用于生成API接口文档)

SpringDoc OpenAPI 是一个基于 OpenAPI 3.0/3.1 规范的工具，用于为 Spring Boot 应用生成 API 文档。它是 springfox（Swagger 2.x）的现代替代方案，完全支持 Spring Boot 3.x 和 JDK 17+，具有更强的兼容性和功能。

---

1. SpringDoc OpenAPI 核心概念

(1) OpenAPI 规范

• OpenAPI（原 Swagger 规范）是描述 RESTful API 的行业标准，支持 API 文档、测试和客户端代码生成。
• SpringDoc OpenAPI 自动将 Spring Boot 的控制器、模型等转换为 OpenAPI 格式，并生成交互式 UI（Swagger UI）。

(2) 与 Spring Boot 的集成

• 自动扫描：无需手动配置，SpringDoc 会自动扫描 @RestController、@RequestMapping 等注解的 API。
• 注解支持：通过 @Operation、@Tag 等注解丰富文档内容。
• 支持现代技术栈：兼容 WebFlux、Kotlin、Jakarta EE 9+ 等。

(3) 关键组件

• OpenAPI 对象：定义 API 的元信息（标题、描述、版本等）。
• @Tag 注解：对 API 进行分类（如用户管理、订单管理）。
• @Operation 注解：描述单个 API 操作（如 GET、POST）。
• @Schema 注解：描述模型类的字段（如用户 ID、用户名）。

---

2. SpringDoc OpenAPI 核心知识点

(1) 依赖与版本

• Maven 依赖：

  <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version> <!-- 最新稳定版 -->
  </dependency>
  

• 版本选择：
  • 2.x 系列支持 Spring Boot 3.x 和 OpenAPI 3.0。
  • 如果需要 OpenAPI 3.1，可以使用 springdoc-openapi-starter-webmvc-api。

(2) 配置方式

• 自动配置：
  • 默认配置下，SpringDoc 会自动生成 API 文档，无需额外代码。
• 自定义配置：
  • 通过 OpenAPI 对象自定义元信息（如标题、描述）。
  • 通过 @Tag 和 @Operation 注解补充 API 细节。

(3) 常用注解

注解	作用
@Tag	对 API 进行分类（如 @Tag(name = "用户管理")）。
@Operation	描述单个 API 操作（如 @Operation(summary = "获取用户")）。
@Schema	描述模型类的字段（如 @Schema(description = "用户ID")）。
@Parameter	描述请求参数（如 @Parameter(description = "用户ID")）。
@ApiResponse	描述响应状态码和内容（如 @ApiResponse(responseCode = "200")）。

(4) 执行路径

• Swagger UI 路径：
  • 默认访问：http://localhost:8080/swagger-ui.html。
  • 可通过配置修改路径：

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

• OpenAPI JSON 路径：
  • 默认访问：http://localhost:8080/v3/api-docs。
  • 支持分组 API 的 JSON 路径（如 /v3/api-docs/public）。

---

3. SpringDoc OpenAPI 的工作流程

1. 启动应用：
   • SpringDoc 自动扫描所有 @RestController 和 @RequestMapping 注解的 API。
2. 生成文档：
   • 根据控制器、模型和注解生成 OpenAPI 3.0/3.1 格式的 JSON。
3. 渲染 UI：
   • 通过 Swagger UI 渲染交互式文档，支持测试 API。

---

4. 高级功能

(1) 分组 API

• 将 API 按功能分组（如公共 API、管理员 API）：

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

• 访问分组后的 Swagger UI：
  • http://localhost:8080/swagger-ui/index.html#/public

(2) 安全性集成

• 如果项目启用了 Spring Security，需要允许访问 Swagger UI：

  @Configuration
  public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/swagger-ui.html", "/v3/api-docs/**").permitAll().anyRequest().authenticated();}
  }
  

(3) 自定义 UI 配置

• 修改 Swagger UI 的标题、布局等：

  @Bean
  public UIConfiguration uiConfig() {return UIConfiguration.builder().deepLinking(true).displayOperationId(false).docExpansion(DocExpansion.NONE).build();
  }
  

(4) 支持 OpenAPI 3.1

• 使用 springdoc-openapi-starter-webmvc-api 依赖：

  <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-api</artifactId><version>2.3.0</version>
  </dependency>
  

---

5. 与 Spring Boot 3.x 的兼容性

• 为什么不用 springfox？
  • springfox（Swagger 2.x）依赖了已移除的 Spring MVC 组件（如 PathPatternParser），无法与 Spring Boot 3.x 兼容。
  • SpringDoc OpenAPI 是专门为 Spring Boot 3.x 和 Jakarta EE 9+ 设计的。

---

6. 总结

• 优势：
  • 完全兼容 Spring Boot 3.x 和 JDK 17+。
  • 支持 OpenAPI 3.0/3.1，功能更强大。
  • 无需手动配置，自动扫描 API。
• 适用场景：
  • 需要快速生成 API 文档的 Spring Boot 项目。
  • 需要支持 OpenAPI 3.0/3.1 的现代应用。
• 对比 springfox：
  • SpringDoc 是 springfox 的替代方案，推荐在新项目中使用。

通过 SpringDoc OpenAPI，可以轻松为 Spring Boot 应用生成高质量的 API 文档，并支持交互式测试。