SpringDoc-OpenApi 现代化 API 文档生成工具介绍+使用
一、介绍
SpringDoc-OpenAPI 是一个专为 Spring Boot 应用设计的现代化 API 文档生成工具，它基于 OpenAPI 3.0 规范，能够自动生成高质量的 RESTful API 文档。
目前它已经成为 Spring Boot 生态中 API 文档生成的标准解决方案，特别是在 Spring Boot 3.x 时代完全替代了已停止维护的 SpringFox。
二、特点
1. 现代化标准支持
- OpenAPI 3.0+ 规范：完全支持最新的 OpenAPI 3.0 和 3.1 规范
- Spring Boot 兼容性：完美支持 Spring Boot 1.x、2.x 和 3.x 版本
- Jakarta EE 支持：适配 Spring Boot 3.x 的 Jakarta EE 9+ 命名空间
2. 自动化文档生成
- 零配置启动：只需添加依赖即可开始工作，无需复杂配置
- 智能代码扫描：自动检测
@RestController、@RequestMapping等注解 - 动态文档更新：随着代码变更自动更新文档，保持同步
3. 强大的 UI 界面
- Swagger UI 集成：内置现代化的 Swagger UI 界面
- 交互式体验：支持在线 API 测试和调试
- 响应式设计：适配各种设备屏幕
与 SpringFox 的对比
| 特性 | SpringDoc-OpenAPI | SpringFox |
|---|---|---|
| 维护状态 | ✅ 活跃更新 | ❌ 停止维护 |
| OpenAPI 3 支持 | ✅ 完整支持 | ❌ 有限支持 |
| Spring Boot 3.x | ✅ 完全支持 | ❌ 不兼容 |
| Jakarta EE | ✅ 支持 | ❌ 不支持 |
| 启动配置 | ✅ 零配置 | ⛔ 复杂配置 |
| 性能 | ✅ 优秀 | ⚠️ 一般 |
三、核心功能模块
SpringDoc-OpenAPI 提供了多个功能模块以适应不同的应用场景：
1. 核心模块
- springdoc-openapi-starter-webmvc-ui：Web MVC 项目的一站式 starter
- springdoc-openapi-webmvc-core：核心功能模块
- springdoc-openapi-ui：Swagger UI 集成模块
2. 扩展模块
- springdoc-openapi-security：Spring Security 支持
- springdoc-openapi-data-rest：Spring Data REST 支持
- springdoc-openapi-hateoas：Spring HATEOAS 支持
- springdoc-openapi-webflux-ui：WebFlux 响应式支持
四、使用步骤
1. 添加依赖
Maven 配置：
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version></dependency>
2. 基本配置
application.yml 配置：
# springdoc swagger配置
springdoc:api-docs:enabled: true # api-docs是否启用path: /v3/api-docs # api-docs访问路径swagger-ui:enabled: true # swagger-ui是否启用path: /swagger-ui.html # swagger-ui访问路径packages-to-scan: com.breeze.upload.controller # 扫描的包，自行更改！路径要写对！paths-to-match: /api/** # 匹配的接口路径，自行更改3. 访问文档
启动应用后，可以通过以下地址访问文档(注意：要改成自己的访问路径和端口)：
- Swagger UI：http://localhost:8080/swagger-ui.html
- OpenAPI JSON：http://localhost:8080/v3/api-docs
- OpenAPI YAML：http://localhost:8080/v3/api-docs.yaml
五、效果展示
Swagger UI：
OpenAPI JSON：
OpenAPI YAML：
六、核心注解
SpringDoc-OpenAPI 使用 OpenAPI 3 标准注解。
1. 控制器级别注解
@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户注册、查询、更新和删除操作")
public class UserController {// 接口方法
}
2. 方法级别注解
@Operation(summary = "创建用户",description = "创建新用户并返回用户信息",tags = {"用户管理"},responses = {@ApiResponse(responseCode = "201", description = "用户创建成功"),@ApiResponse(responseCode = "400", description = "无效的请求参数"),@ApiResponse(responseCode = "409", description = "用户名已存在")}
)
@PostMapping
public ResponseEntity<User> createUser(@Parameter(description = "用户创建请求", required = true)@RequestBody @Valid CreateUserRequest request
) {// 业务逻辑return ResponseEntity.status(HttpStatus.CREATED).body(user);
}
3. 模型类注解
@Schema(name = "用户", description = "用户基本信息")
public class User {@Schema(description = "用户ID", example = "1001", requiredMode = Schema.RequiredMode.REQUIRED)private Long id;@Schema(description = "用户名", example = "john_doe", maxLength = 50)private String username;@Schema(description = "邮箱", example = "john@example.com", format = "email")private String email;@Schema(description = "创建时间", example = "2024-01-01T12:00:00Z")private LocalDateTime createTime;// getter 和 setter
}
4. 常用注解对照表
| 用途 | SpringDoc (OpenAPI 3) | SpringFox (Swagger 2) |
|---|---|---|
| API 分组 | @Tag(name = "分组名") | @Api(tags = "分组名") |
| 方法描述 | @Operation(summary = "摘要") | @ApiOperation(value = "描述") |
| 参数描述 | @Parameter(description = "说明") | @ApiParam("说明") |
| 模型描述 | @Schema(description = "说明") | @ApiModelProperty("说明") |
| 响应描述 | @ApiResponse(responseCode = "200") | @ApiResponse(code = 200) |
七、高级配置
1. 自定义 OpenAPI 信息
@Configuration
public class SpringDocConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("用户管理系统 API").version("1.0.0").description("用户管理系统的 RESTful API 文档").contact(new Contact().name("技术团队").email("tech@example.com").url("https://example.com")).license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0.html"))).externalDocs(new ExternalDocumentation().description("用户手册").url("https://example.com/docs"));}
}2. 接口分组配置
@Bean
public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public").pathsToMatch("/api/public/**").build();
}@Bean
public GroupedOpenApi adminApi() {return GroupedOpenApi.builder().group("admin").pathsToMatch("/api/admin/**").addOpenApiMethodFilter(method -> method.isAnnotationPresent(AdminApi.class)).build();
}3. 安全认证配置
@Bean
public OpenAPI secureOpenAPI() {return new OpenAPI().components(new Components().addSecuritySchemes("bearerAuth", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"))).addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
}4. 全局响应配置
@Bean
public OpenApiCustomiser globalResponseCustomiser() {return openApi -> openApi.getPaths().values().forEach(pathItem ->pathItem.readOperations().forEach(operation -> {operation.getResponses().addApiResponse("400", new ApiResponse().description("请求参数错误"));operation.getResponses().addApiResponse("401", new ApiResponse().description("未授权访问"));operation.getResponses().addApiResponse("403", new ApiResponse().description("权限不足"));operation.getResponses().addApiResponse("500", new ApiResponse().description("服务器内部错误"));}));
}八、配置属性详解
springdoc:# API文档基本配置api-docs:enabled: true # 是否启用API文档path: /v3/api-docs # API文档路径version: openapi_3_1 # OpenAPI版本packages-to-scan: com.example.controller # 扫描包路径paths-to-match: /api/** # 路径匹配规则paths-to-exclude: /error/** # 排除路径# Swagger UI配置swagger-ui:enabled: true # 是否启用Swagger UIpath: /swagger-ui.html # UI访问路径doc-expansion: none # 文档展开方式default-model-expand-depth: 2 # 默认模型展开深度supported-submit-methods: # 支持的提交方法- get- post- put- delete# 缓存配置cache:disabled: false # 是否禁用缓存# 分组配置group-configs:- group: publicpaths-to-match: /api/public/**- group: adminpaths-to-match: /api/admin/**# 其他配置show-actuator: false # 是否显示Actuator端点auto-tag-classes: true # 是否自动根据类名生成Tagpre-loading-enabled: false # 是否预加载文档