一、与Swagger的关系
时间线:
- 2010 年,Wordnik 的 Tony Tam 做了 Swagger,用来描述 REST API;
- Swagger 2.0 规范加上 Swagger UI / Editor / Codegen 工具链,成为事实标准;
- 2015 年 Swagger 规范捐给 Linux 基金会,2016 年改名为 OpenAPI Specification (OAS),2017 年 OAS 3.0 发布------从此 OpenAPI 是规范,Swagger 是工具品牌;
- SpringFox 曾是 Spring 生态最流行的实现,但 2020 年 3.0.0 之后基本停更:Spring Boot 2.6 默认路径匹配策略切到 PathPatternParser 后大面积启动报错,Spring Boot 3(Jakarta EE 9)直接不兼容;
- SpringDoc 接棒:运行时扫描 Spring 配置、类结构和注解,自动生成 OpenAPI 3 文档(JSON/YAML),并内置 Swagger UI 渲染。
总结:OpenAPI 是"文档的格式标准",Swagger UI 是"看文档的界面",SpringDoc 是"自动生成文档的引擎" 。 @Operation 注解来自 io.swagger.v3.oas.annotations(Swagger 的注解库),文档格式是 OpenAPI 3,渲染界面是 Swagger UI------三者协作,各司其职。
二、SpringDoc 的特色
- 零配置 :加依赖就有文档,默认
/v3/api-docs(JSON)、/v3/api-docs.yaml、/swagger-ui.html; - 注解 + JSR-303 联动 :
@NotNull、@Min、@Max、@Size自动映射为 Schema 约束,前端看到的校验规则和后端真实校验一致; - 分组多文档 :
GroupedOpenApi按包/路径拆出 admin、open 等多份文档; - 全栈支持:WebMVC / WebFlux 双栈、Kotlin、GraalVM Native Image;3.x 还支持 Scalar UI 和 MCP(AI 工具调用那套协议);
- 扩展点丰富 :
OpenApiCustomizer/OperationCustomizer全局改文档,OAuth2 / JWT 安全方案一行代码接入; - 社区活跃:非 Pivotal 官方维护,但迭代节奏跟得上 Spring Boot 大版本。
版本矩阵:
| Spring Boot | SpringDoc | 依赖坐标 |
|---|---|---|
| 1.x / 2.x | 1.8.x | springdoc-openapi-ui |
| 3.x | 2.10.x | springdoc-openapi-starter-webmvc-ui |
| 4.x | 3.2.x | springdoc-openapi-starter-webmvc-ui(Java 17+) |
从 2.8.7 起官方提供 BOM(springdoc-openapi-bom),多模块项目建议用它统一管理版本。
三、快速上手(Spring Boot 4 + SpringDoc 3.2)
第一步:引依赖
xml
<dependencyManagement>
<dependencies>
<!-- BOM 统一管理 springdoc 版本,子模块不用重复写 version -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-bom</artifactId>
<version>3.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<!-- WebMVC + 内置 Swagger UI;只要 JSON 不要 UI 时改用 starter-webmvc-api -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>
</dependencies>
第二步:基础配置
yaml
springdoc:
api-docs:
path: /v3/api-docs # OpenAPI JSON 地址
swagger-ui:
path: /swagger-ui.html # UI 地址
operations-sorter: method # 按 HTTP 方法排序,方便阅读
packages-to-scan: com.example.demo.controller # 只扫业务包,避免 actuator 混进文档
第三步:给 Controller 加注解
java
package com.example.demo.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@Tag(name = "用户接口", description = "用户注册、查询相关接口") // 对应 UI 左侧分组
@RestController
@RequestMapping("/api/users")
public class UserController {
/** @Operation 描述接口,@Parameter 描述查询参数;JSR-303 约束自动进文档 */
@Operation(summary = "分页查询用户", description = "按页返回用户列表,page 从 1 开始")
@GetMapping
public List<String> list(
@Parameter(description = "页码") @RequestParam(defaultValue = "1") @Min(1) int page,
@Parameter(description = "每页条数,最大 100") @RequestParam(defaultValue = "10") @Max(100) int size) {
return List.of("user-" + page + "-" + size);
}
/** @Valid 让 JSR-303 校验生效;请求体字段约束会体现在 Schema 中 */
@Operation(summary = "创建用户")
@PostMapping
public String create(@Valid @RequestBody CreateUserReq req) {
return "created: " + req.name();
}
/** 请求体模型:@Schema 描述字段,与 JSR-303 注解共同构成文档 */
public record CreateUserReq(
@Schema(description = "用户名", example = "tom") @NotBlank String name,
@Schema(description = "年龄", example = "18") @Min(0) @Max(150) Integer age) {
}
}
第四步:配置文档元信息 + JWT 鉴权 + 分组
java
package com.example.demo.config;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
/** 全局文档信息 + JWT 方案:UI 右上角会出现 Authorize 按钮 */
@Bean
public OpenAPI demoOpenAPI() {
String scheme = "BearerAuth";
return new OpenAPI()
.info(new Info().title("Demo 服务 API").version("v1.0.0")
.description("SpringDoc 3.2 + Spring Boot 4 示例"))
// 声明 Bearer Token 鉴权方案
.components(new Components().addSecuritySchemes(scheme,
new SecurityScheme().type(SecurityScheme.Type.HTTP)
.scheme("bearer").bearerFormat("JWT")))
// 全局应用该方案,单个接口也可用 @SecurityRequirement 覆盖
.addSecurityItem(new SecurityRequirement().addList(scheme));
}
/** 分组文档:/v3/api-docs/admin 只包含 /api/admin/** 的接口 */
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("admin")
.pathsToMatch("/api/admin/**")
.build();
}
}
启动后访问 http://localhost:8080/swagger-ui.html 即可;OpenAPI JSON 在 /v3/api-docs,分组文档在 /v3/api-docs/admin。
四、生产场景:网关聚合与文档即代码
场景 1:微服务网关聚合文档。 每个服务各自暴露 /v3/api-docs,网关侧(WebFlux 栈用 springdoc-openapi-starter-webflux-ui)用 Swagger UI 的 urls 配置统一入口,下拉切换:
yaml
# 网关服务配置
springdoc:
swagger-ui:
urls:
- name: 用户服务
url: /user-service/v3/api-docs # 网关路由转发到用户服务
- name: 订单服务
url: /order-service/v3/api-docs
配合网关路由的 RewritePath 把 /user-service/** 转发到后端服务,文档和真实接口走同一套路由,不会出现"文档地址对不上"的问题。
场景 2:文档即代码(CI 导出 + SDK 生成)。 在流水线里把 openapi.json 导出为构建产物,交给 openapi-generator 生成前端 TypeScript SDK / Java Client------接口一改,SDK 自动更新,接口文档从"附件"变成"契约":
yaml
# CI 步骤示例:应用启动后抓取 OpenAPI 契约文件
- name: Export OpenAPI spec
run: |
mvn -q spring-boot:run -Dspring-boot.run.profiles=ci & # 后台启动应用
sleep 20
curl -sf http://localhost:8080/v3/api-docs -o openapi.json # 抓取契约
kill %1 # 关闭应用
也可以改用 springdoc-openapi-maven-plugin,在 integration-test 阶段自动启动应用并抓取文档,产物默认写到 target/openapi.json,适合和 openapi-generator-maven-plugin 串在一条构建链上。
五、踩坑
- 版本错配:Boot 3 配 springdoc 1.x 会因 javax/jakarta 冲突起不来;Boot 4 必须用 3.x;
- springfox 残留 :老项目升级时务必删干净
springfox-*依赖,两套注解/扫描器共存会导致文档重复、Tag 混乱; - 生产暴露风险 :文档页会暴露全部接口结构,生产环境建议
springdoc.api-docs.enabled=false且springdoc.swagger-ui.enabled=false,或把文档挂到网关鉴权之后; - Security 放行 :Spring Security 下要放行
/v3/api-docs/**、/swagger-ui/**、/swagger-ui.html,否则 UI 白屏; - 扫描范围 :用
packages-to-scan限定业务包,避免 actuator、错误页混进文档; - 泛型/循环引用 :复杂泛型返回会生成晦涩的 Schema 名,必要时用
@Schema(name = "...")显式命名。
六、总结
- Swagger 是工具品牌,OpenAPI 是规范,SpringDoc 是 Spring 生态的文档生成引擎;
- SpringFox 已停更,SpringDoc 是 Boot 3/4 时代的事实标准;
- 用对版本(Boot 4 → 3.2.x)、加好注解、配好分组和鉴权,文档就从"负担"变成"契约":网关聚合统一入口,CI 导出生成 SDK,接口变更自动进流水线。