Springdoc的常用注解（Swagger3标准的OpenAPI 3 规范）

Springdoc 常用注解与 Swagger2 对比指南

Springdoc官网：https://springdoc.org/
在这里插入图片描述
Swagger2官网：https://swagger.io/

一、Springdoc 常用注解及对应 Swagger2 注解

以下是 Springdoc 的核心注解及其与 Swagger2 的对比，帮助开发者快速迁移和理解差异：

用途	Springdoc (OpenAPI 3)	Swagger2 (Springfox)	说明
API 分组	`@Tag(name = "分组名")`	`@Api(tags = "分组名")`	定义接口模块分组，作用于类或方法。Springdoc 的 `@Tag` 更灵活，支持 `description` 字段。
接口方法描述	`@Operation(summary = "摘要")`	`@ApiOperation(value = "描述")`	描述单个接口的作用。Springdoc 的 `@Operation` 支持更多字段，如 `tags`、`hidden` 等。
参数描述	`@Parameter(description = "参数说明")`	`@ApiParam("参数说明")`	描述方法参数。Springdoc 的 `@Parameter` 支持 `required`、`example` 等更细粒度配置。
模型字段描述	`@Schema(description = "字段说明")`	`@ApiModelProperty("字段说明")`	描述 DTO 或模型的字段。`@Schema` 支持 `example`、`nullable` 等扩展属性。
响应结构定义	`@ApiResponse(responseCode = "200", description = "成功")`	`@ApiResponse(code = 200, message = "成功")`	定义接口返回的 HTTP 状态码和描述。Springdoc 使用 `responseCode` 替代 `code`。
全局安全配置	`@SecurityScheme` + `@SecurityRequirement`	`@ApiKeyAuthDefinition` 等	Springdoc 通过 `@SecurityScheme` 定义安全方案（如 OAuth2、JWT），并在接口上使用 `@SecurityRequirement` 绑定。

二、详细注解使用示例

1. API 分组与接口描述

// Springdoc
@RestController
@Tag(name = "用户模块", description = "用户注册、登录、查询等操作")
public class UserController {@Operation(summary = "获取用户信息",description = "根据用户ID查询详细信息",tags = {"查询类接口"})@GetMapping("/users/{id}")public User getUser(@Parameter(description = "用户ID", example = "1001") @PathVariable Long id) {// ...}
}// Swagger2
@RestController
@Api(tags = "用户模块", description = "用户相关操作")
public class UserController {@ApiOperation(value = "获取用户信息", notes = "根据ID查询")@GetMapping("/users/{id}")public User getUser(@ApiParam("用户ID") @PathVariable Long id) {// ...}
}

2. 模型字段描述

// Springdoc
public class User {@Schema(description = "用户ID", example = "1001", requiredMode = Schema.RequiredMode.REQUIRED)private Long id;@Schema(description = "用户名", example = "john_doe", maxLength = 20)private String username;
}// Swagger2
public class User {@ApiModelProperty(value = "用户ID", example = "1001", required = true)private Long id;@ApiModelProperty(value = "用户名", example = "john_doe")private String username;
}

3. 安全认证配置

// Springdoc
@Configuration
@SecurityScheme(name = "BearerAuth",type = SecuritySchemeType.HTTP,scheme = "bearer",bearerFormat = "JWT"
)
public class OpenApiConfig {}@Operation(summary = "删除用户", security = @SecurityRequirement(name = "BearerAuth"))
@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable Long id) {// ...
}// Swagger2
@Configuration
public class SwaggerConfig {@Beanpublic SecurityConfiguration security() {return new SecurityConfiguration("client-id", "client-secret", "realm","app-name", "apiKey", ApiKeyVehicle.HEADER, "Authorization", ",");}
}@ApiOperation(value = "删除用户")
@ApiImplicitParams({@ApiImplicitParam(name = "Authorization", value = "JWT Token", required = true, dataType = "string", paramType = "header")
})
@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable Long id) {// ...
}

三、Springdoc 与 Swagger2 的核心差异

对比维度	Springdoc	Swagger2 (Springfox)
规范支持	支持 OpenAPI 3.0+（现代标准，兼容性更强）	仅支持 Swagger 2.0（旧版规范）
维护状态	活跃维护，适配 Spring Boot 3.x	已停止维护（2020年后无更新）
路径匹配策略	兼容 Spring Boot 2.6+ 的 `PathPatternParser`	在 Spring Boot 2.6+ 中因路径策略变更可能失效
注解包路径	`io.swagger.v3.oas.annotations`	`io.swagger.annotations`
异步接口支持	支持 Reactive（如 WebFlux）、Servlet 异步	对异步接口支持较弱
安全性配置	通过 `@SecurityScheme` 灵活定义多种认证方式	配置较为繁琐，依赖 `SecurityConfiguration`
UI 自定义	提供主题切换、路径修改等配置项	自定义需修改静态资源或 CSS

四、迁移注意事项

依赖替换
移除 springfox-swagger2 和 springfox-swagger-ui，添加 Springdoc 依赖：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version>
</dependency>

注解包替换
将 io.swagger.annotations 替换为 io.swagger.v3.oas.annotations。
配置调整
- 文档访问路径：Swagger2 的 swagger-ui.html 变为 Springdoc 的 swagger-ui/index.html。
- 分组配置：使用 GroupedOpenApi 替代 Docket。
解决常见问题
- 注解不生效：检查是否使用了正确的包路径。
- 文档空白：确保未拦截 /v3/api-docs 和 /swagger-ui/** 路径（如 Spring Security 配置）。