SpringDoc 基本使用指南

SpringDoc 是基于 Spring Boot 的现代化 API 文档生成工具，通过自动化扫描代码和注解，生成符合 OpenAPI 3.0+ 规范 的交互式文档，并集成 Swagger UI 提供可视化测试界面。以下是其核心详解：

核心特性与优势

• 开箱即用仅需添加依赖，无需复杂配置即可自动生成文档，支持 Spring WebMvc、WebFlux、Spring Security 及 Jakarta EE。
• 注解驱动使用 JSR-303 规范注解（如 @Tag、@Operation）替代 SpringFox 专属注解，降低学习成本。
• 动态兼容性完美适配 Spring Boot 2.6+ 及 3.x（含 JDK 17+），解决 SpringFox 因停维护导致的不兼容问题。
• 多格式输出支持 JSON/YAML/HTML 格式文档，并提供分组功能，可按模块划分接口（如公开 API 与内部 API）。

集成与配置

全局信息配置类（可选）

@Configuration
@OpenAPIDefinition(
    info = @Info(title = "项目 API 文档", version = "1.0", description = "SpringBoot 接口文档")
)
public class SpringDocConfig {
    // 无需额外代码
}

基础配置（application.yml）

springdoc:
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
    persistAuthorization: true
    disable-swagger-default-url: true
  api-docs:
    enabled: true
    path: /v3/api-docs
    default-consumes-media-type: application/json
    default-produces-media-type: application/json
  cache:
    disabled: false