Swagger 3 (OpenAPI 3.0) 常用注解大全

1. 控制器（Controller）相关注解

1.1 类级别注解

• @Tag(name = "用户管理", description = "用户管理相关接口") - 为控制器添加标签，用于API分组
• @SecurityRequirement(name = "bearerAuth") - 指定此控制器的所有接口需要认证

import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户管理相关接口")
@SecurityRequirement(name = "bearerAuth")
public class UserController {
    // 控制器方法
}

1.2 方法级别注解

• @Operation(summary = "创建用户", description = "创建一个新用户") - 描述API操作
• @ApiResponse(responseCode = "200", description = "成功创建用户") - 描述API响应
• @ApiResponses - 包含多个@ApiResponse
• @Parameter(name = "id", description = "用户ID", required = true) - 描述参数
• @RequestBody(description = "用户信息", required = true) - 描述请求体

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;

@Operation(summary = "获取用户详情", description = "根据ID获取用户详细信息")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功获取用户信息", 
                 content = @Content(mediaType = "application/json", 
                 schema = @Schema(implementation = UserDTO.class))),
    @ApiResponse(responseCode = "404", description = "用户不存在"),
    @ApiResponse(responseCode = "500", description = "服务器内部错误")
})
@GetMapping("/{id}")
public ResponseEntity<UserDTO> getUserById(
    @Parameter(description = "用户ID", required = true) @PathVariable Long id) {
    // 方法实现
}

@Operation(summary = "创建用户", description = "创建一个新用户")
@PostMapping
public ResponseEntity<UserDTO> createUser(
    @io.swagger.v3.oas.annotations.parameters.RequestBody(
        description = "用户信息", required = true,
        content = @Content(schema = @Schema(implementation = CreateUserRequest.class))
    )
    @RequestBody CreateUserRequest request) {
    // 方法实现
}

2. 模型（DTO/实体类）相关注解

2.1 类级别注解

• @Schema(description = "用户信息") - 描述模型

2.2 字段级别注解

• @Schema(description = "用户ID", example = "1") - 描述字段，提供示例

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户信息DTO")
public class UserDTO {
    
    @Schema(description = "用户ID", example = "1")
    private Long id;
    
    @Schema(description = "用户名", example = "john_doe", required = true)
    private String username;
    
    @Schema(description = "用户邮箱", example = "[email protected]", required = true)
    private String email;
    
    @Schema(description = "用户角色", example = "ADMIN", allowableValues = {"USER", "ADMIN", "MANAGER"})
    private String role;
    
    @Schema(description = "创建时间", example = "2023-01-01T12:00:00Z", accessMode = Schema.AccessMode.READ_ONLY)
    private LocalDateTime createdAt;
    
    // 省略getter和setter
}

3. 枚举类型处理