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


