Swagger 全量注解应用指南：从@Tag到@SecurityScheme，全面掌握API设计

注解

适用范围

属性

说明

示例

@Tag

类

name

： （必填）  标签名称。 description：标签描述。

用于对API操作进行逻辑分组。一个控制器可以有多个标签。在Swagger UI中显示为不同的分类。

@Tag(name = "用户管理", description = "用户的增删改查API")

@Hidden

类、方法

无

隐藏

被注解的类或方法，不会出现在生成的API文档中。

@Hiddenpublic class InternalController { ... }

注解

适用范围

属性

说明

示例

@Operation

方法

summary

：操作摘要。 description：详细描述。 method：指定HTTP方法（通常不需要，由@GetMapping等隐含）。 tags：覆盖类级别的标签，为该操作指定新的分组。

描述一个HTTP请求操作（如一个GET或POST端点），是方法上最重要的注解。

@Operation(summary = "创建用户", description = "根据传入的用户信息创建一个新用户")

@ApiResponse

方法

responseCode

： （必填）  HTTP状态码，如 "200", "404"。 description：响应的描述。 content：指定响应内容（使用@Content）。

声明一个操作可能返回的响应。通常与@Operation的responses属性一起使用，描述各种可能的返回结果。

@ApiResponse(responseCode = "404", description = "用户不存在")

@ApiResponses

方法

value

：一个@ApiResponse注解的数组。

当需要声明多个响应时，用它来包裹多个@ApiResponse。

@ApiResponses(value = {@ApiResponse(responseCode = "200", ...),@ApiResponse(responseCode = "400", ...)})

@Callback

方法

name

：回调名称。 callbackUrlExpression：回调URL表达式。

描述一个回调操作，用于Webhooks等异步通知场景，使用相对较少。

(略复杂，此处不展开示例)

注解

适用范围

属性

说明

示例

@Parameter

参数

description

：参数描述。 required：是否必填，默认为false。 example：提供示例值。 hidden：是否隐藏该参数。 schema：指定参数的schema（使用@Schema）。

描述一个操作参数，如@PathVariable, @RequestParam, @RequestHeader, @CookieValue等。注意：@RequestBody参数通常不用此注解，而是用@Schema。

public User getUserById(@Parameter(description = "用户ID", example = "123", required = true)@PathVariable Long id) {...}

@Parameters

方法

value

：一个@Parameter注解的数组。

当需要在方法上为多个参数添加描述时，用它来包裹多个@Parameter。

@Parameters({@Parameter(name = "id", description = "ID"),@Parameter(name = "name", description = "名称")})

@RequestHeader

参数

与@Parameter属性相同。

它是@Parameter的一个特殊化，专门用于描述请求头参数，会在UI上被单独分组显示。

@RequestHeader(@Parameter(description = "认证令牌", required = true)) String authToken

注解

适用范围

属性

说明

示例

@RequestBody

参数

description

：请求体的描述。 required：是否必填。 content：指定请求体的媒体类型和结构（使用@Content）。

专门用于描述@RequestBody参数

。提供对请求体的详细说明。

@RequestBody(description = "用户信息", required = true, content = @Content(schema = @Schema(implementation = User.class))) User user

@Content

与@RequestBody或@ApiResponse的content属性一起使用

schema

：指定内容的schema（使用@Schema）。 mediaType：指定媒体类型，如 "application/json"。 examples：提供多个示例（使用@ExampleObject）。

定义请求或响应体的媒体类型和结构。

content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))

@Schema

模型类

、模型属性、参数

description

：描述。 example：提供示例值。 requiredMode：指定是否必须（Schema.RequiredMode.REQUIRED）。 implementation：指定关联的类（用于在@Content中）。 allowableValues：限制允许的值。

这是最重要的模型注解

。用于描述DTO（数据传输对象）、VO（值对象）等模型，或修饰@RequestBody/响应体的结构。

@Schema(description = "用户实体", requiredMode = Schema.RequiredMode.REQUIRED)public class User {@Schema(description = "用户ID", example = "1")private Long id;}

注解

适用范围

属性

说明

示例

@SecurityScheme

类

（配置类）

type

：安全方案类型（如SecurityScheme.Type.HTTP）。 scheme：方案（如 "bearer"）。 bearerFormat：承载格式（如 "JWT"）。 name：方案名称（用于@SecurityRequirement）。 in：ApiKey类型时，token的位置（SecurityScheme.In.HEADER）。

在配置类中定义全局的安全方案

，如JWT、OAuth2、ApiKey等。

见下方配置示例

@SecurityRequirement

类

、方法

name

：引用的安全方案名称。 scopes：所需的OAuth作用域（数组）。

声明一个操作或整个控制器需要哪些安全方案。在Swagger UI中会出现Authorize按钮。

@SecurityRequirement(name = "bearerAuth")