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）。
集成与配置
依赖引入（Spring Boot 3.x）
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.5.0</version> <!-- 官方稳定版，兼容 Spring Boot 3.3.x:cite[2]:cite[8] --> </dependency>AI写代码xm
基础配置（application.yml）
springdoc: swagger-ui: # 开启 swagger-ui 文档展示 enabled: true # UI访问路径 path: /swagger-ui.html # 标签排序方式 tags-sorter: alpha # 操作排序方式 operations-sorter: alpha # 保持认证状态 persistAuthorization: true # 禁用示例接口 disable-swagger-default-url: true api-docs: # 开启 OpenAPI 展示 enabled: true # OpenAPI JSON路径 path: /v3/api-docs default-consumes-media-type: application/json default-produces-media-type: application/json cache: # 关闭文档缓存 disabled: false # 显示actuator端点 show-actuator: false # 推荐保持默认，显示结构化参数 # default-flat-param-object: true # 允许在文档中展示 Spring MVC 的 ModelAndView 返回类型 model-and-view-allowed: true # 推荐关闭以确保文档精确性 override-with-generic-response: falseAI写代码yaml
全局信息配置类（可选）
@Configuration @OpenAPIDefinition( info = @Info(title = "项目API文档", version = "1.0", description = "SpringBoot接口文档") ) public class SpringDocConfig { // 无需额外代码 }AI写代码jav
注解使用
常用注解
| 场景 | SpringDoc 注解 | 示例 |
|---|---|---|
| 控制器描述 | @Tag(name="模块", description="") | @Tag(name="用户管理", description="用户CRUD") |
| 接口方法描述 | @Operation(summary="", description="") | @Operation(summary="创建用户", description="需管理员权限") |
| 参数描述 | @Parameter(description="") | @Parameter(description="用户ID", required=true) |
| 模型属性描述 | @Schema(description="") |
