Swagger 是一个强大的 API 文档生成工具，在 Spring Boot 项目中主要通过 springdoc-openapi 库实现。下面我将详细讲解 Swagger 的配置、注解使用和高级功能。
一、基础配置
1. 添加依赖
在 pom.xml 中添加：
xml
复制
下载
运行
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.5.0</version> <!-- 检查最新版本 -->
</dependency>
2. 基础配置（application.properties）
properties
复制
下载
# 启用 Swagger springdoc.api-docs.enabled=true # 文档基本信息配置 springdoc.swagger-ui.path=/swagger-ui.html springdoc.api-docs.path=/v3/api-docs springdoc.info.title=订单管理系统 API springdoc.info.description=订单管理系统的 RESTful API 文档 springdoc.info.version=1.0.0 springdoc.info.contact.name=技术支持 springdoc.info.contact.email=support@example.com springdoc.info.license.name=Apache 2.0 springdoc.info.license.url=https://www.apache.org/licenses/LICENSE-2.0
二、核心注解使用
1. Controller 层注解
java
复制
下载
@RestController
@RequestMapping("/api/orders")
@Tag(name = "订单管理", description = "订单的创建、查询和管理操作")
public class OrderController {
@Operation(
summary = "创建新订单",
description = "创建一个新的订单记录",
responses = {
@ApiResponse(responseCode = "201", description = "订单创建成功"),
@ApiResponse(responseCode = "400", description = "无效的输入")
}
)
@PostMapping
public ResponseEntity<Order> createOrder(
@RequestBody @Valid
@io.swagger.v3.oas.annotations.parameters.RequestBody(
description = "订单对象",
required = true,
content = @Content(schema = @Schema(implementation = Order.class))
Order order) {
// 实现逻辑
}
@Operation(
summary = "根据ID获取订单",
description = "通过订单ID获取订单详细信息"
)
@GetMapping("/{id}")
public Order getOrderById(
@Parameter(
name = "id",
description = "订单ID",
required = true,
example = "12345"
)
@PathVariable Long id) {
// 实现逻辑
}
@Operation(
summary = "分页查询订单",
description = "根据条件分页查询订单列表"
)
@GetMapping
public Page<Order> getOrders(
@Parameter(description = "页码，从0开始", example = "0")
@RequestParam(defaultValue = "0") int page,
@Parameter(description = "每页记录数", example = "10")
@RequestParam(defaultValue = "10") int size,
@Parameter(description = "排序字段，格式: field[,asc|desc]")
@RequestParam(required = false) String sort) {
// 实现逻辑
}
}
2. 模型类注解
java
复制
下载
@Schema(description = "订单实体")
public class Order {
@Schema(description = "订单ID", example = "1001")
private Long id;
@Schema(description = "订单状态",
allowableValues = {"CREATED", "PAID", "SHIPPED", "COMPLETED", "CANCELLED"},
example = "CREATED")
private String status;
@Schema(description = "订单总金额", example = "199.99")
private BigDecimal totalAmount;
@Schema(description = "创建时间", example = "2023-10-01T12:00:00Z")
private LocalDateTime createdAt;
// Getter/Setter
}
3. 枚举类型注解
java
复制
下载
@Schema(description = "订单状态枚举")
public enum OrderStatus {
@Schema(description = "已创建")
CREATED,
@Schema(description = "已支付")
PAID,
@Schema(description = "已发货")
SHIPPED,
@Schema(description = "已完成")
COMPLETED,
@Schema(description = "已取消")
CANCELLED
}
三、高级配置
1. 自定义全局配置类
java
复制
下载
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("订单管理系统 API")
.version("1.0.0")
.description("订单管理系统的 RESTful API 文档")
.contact(new Contact()
.name("技术支持")
.email("support@example.com"))
.license(new License()
.name("Apache 2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0")))
.externalDocs(new ExternalDocumentation()
.description("项目 Wiki 文档")
.url("https://wiki.example.com"))
.addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
.components(new Components()
.addSecuritySchemes("bearerAuth", new SecurityScheme()
.name("bearerAuth")
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")));
}
}
2. 分组配置
java
复制
下载
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("admin")
.pathsToMatch("/api/admin/**")
.build();
}
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("public")
.pathsToMatch("/api/public/**")
.build();
}
3. 安全配置（JWT 示例）
java
复制
下载
@Operation(summary = "获取用户信息", security = {@SecurityRequirement(name = "bearerAuth")})
@GetMapping("/me")
public User getCurrentUser() {
// 实现逻辑
}
四、常用注解详解
| 注解 | 作用域 | 描述 |
|---|---|---|
@Tag |
Controller | 标记控制器，用于分组和描述 |
@Operation |
方法 | 描述 API 操作（GET/POST/PUT/DELETE 等） |
@Parameter |
参数 | 描述方法参数（路径参数、查询参数等） |
@RequestBody |
参数 | 描述请求体内容 |
@ApiResponse |
方法 | 描述操作的可能响应 |
@Schema |
模型类/属性 | 描述数据模型及其属性 |
@Hidden |
类/方法/属性 | 从文档中隐藏指定的元素 |
@SecurityRequirement |
方法 | 声明操作所需的安全方案 |
五、Swagger UI 高级功能
1. 自定义 UI 配置
properties
复制
下载
# 自定义 UI 路径 springdoc.swagger-ui.path=/custom-swagger # 禁用 Try It Out 功能 springdoc.swagger-ui.supportedSubmitMethods= # 默认展开深度 springdoc.swagger-ui.docExpansion=none # 自定义主题 springdoc.swagger-ui.configUrl=/swagger-config
2. 添加全局请求头
java
复制
下载
@Bean
public OpenApiCustomiser customerGlobalHeaderOpenApiCustomiser() {
return openApi -> openApi.getPaths().values().stream()
.flatMap(pathItem -> pathItem.readOperations().stream())
.forEach(operation -> {
operation.addParametersItem(new HeaderParameter()
.$ref("#/components/parameters/myGlobalHeader"));
});
}
六、生产环境注意事项
1. 禁用 Swagger UI
properties
复制
下载
# 生产环境禁用 Swagger UI springdoc.swagger-ui.enabled=false springdoc.api-docs.enabled=false
2. 条件启用配置
java
复制
下载
@Profile({"dev", "test"})
@Configuration
public class SwaggerConfig {
// 只在 dev/test 环境启用
}
3. 安全保护
java
复制
下载
@Bean
public OpenApiCustomiser securityOpenApiCustomiser() {
return openApi -> openApi.getPaths().values().forEach(pathItem ->
pathItem.readOperations().forEach(operation -> {
operation.setSecurity(Collections.singletonList(
new SecurityRequirement().addList("basicAuth"))
);
})
);
}
七、最佳实践
保持文档同步：将 Swagger 注解作为代码的一部分维护
使用分组：大型项目按模块分组展示 API
提供完整示例：为每个模型属性添加
example值描述错误响应：详细描述可能的错误响应码和内容
结合测试：使用 Swagger 生成测试用例，确保文档准确性
版本控制：API 版本变更时同步更新文档版本
八、访问文档
启动应用后访问：
Swagger UI 界面：
http://localhost:8080/swagger-ui.htmlOpenAPI JSON：
http://localhost:8080/v3/api-docs
九、常见问题解决
404 错误：
检查依赖是否正确添加
确认
springdoc.api-docs.enabled=true
注解不生效：
检查包扫描范围
确保使用正确的注解（
io.swagger.v3.oas.annotations）
模型属性未显示：
确保有公共 getter 方法
或使用
@Schema显式标注
日期格式问题：
java
复制
下载
@Schema(type = "string", format = "date-time") private LocalDateTime createTime;
通过以上详细配置和注解使用，你可以为 Spring Boot 项目生成专业、易用的 API 文档，大大提高开发效率和协作质量。