在使用 springdoc-openapi 时，提供了多个注解用于增强 OpenAPI 文档的描述，使 API 更加清晰易懂。以下是 springdoc-openapi 和 OpenAPI 3 相关的常用注解，按功能分类列出：

1. Controller/Operation 级别注解

这些注解用于为控制器和具体的操作（API 端点）添加描述和信息。

@Operation
用于描述控制器中的单个 API 操作（例如，GET、POST 等方法）。

@Operation(summary = "获取用户信息", description = "通过用户ID获取详细信息")

@Tag
用于为控制器添加一个标签（Tag），可以将 API 归类，通常用于模块化。

@Tag(name = "用户管理", description = "用户相关的API")

@Hidden
隐藏不希望显示在文档中的控制器或方法。

@Hidden

2. 参数注解

这些注解用于描述请求路径、查询参数、请求体等。

@Parameter
为方法参数添加描述（路径变量、查询参数、请求体等）。

@Parameter(description = "用户的唯一ID", example = "1")

@Parameters
允许为一个方法定义多个参数的描述。

@Parameters({
    @Parameter(name = "id", description = "用户ID", required = true),
    @Parameter(name = "type", description = "用户类型", required = false)
})

@RequestBody (Spring MVC 注解)
用于指示方法参数是请求体的内容，springdoc-openapi 会自动扫描它生成相应的文档。你可以结合 @Schema 注解来更好地描述请求体的结构。

@RequestBody(description = "要创建的用户")

@RequestHeader (Spring MVC 注解)
表示 HTTP 请求头。可以和 @Parameter 一起使用来描述。

@RequestHeader(value = "X-Custom-Header") String header

@CookieParam
描述 HTTP 请求中的 Cookie 参数。

@CookieParam(name = "session_id") String sessionId

3. Schema/Model 级别注解

这些注解用于为实体类、DTO 等 Java 对象中的字段添加详细描述。

@Schema
用于描述实体类、字段或方法的架构（Schema），可以提供详细的字段说明。

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

    @Schema(description = "用户名", example = "John Doe")
    private String name;

    @Schema(description = "用户邮箱", example = "john.doe@example.com")
    private String email;
}

@ArraySchema
当字段是一个数组或集合时，使用 @ArraySchema 来描述它。

@ArraySchema(schema = @Schema(description = "角色列表", example = "[\"ADMIN\", \"USER\"]"))
private List<String> roles;

@Content
指定请求体或响应的内容类型。

@PostMapping
@Operation(summary = "上传文件")
@RequestBody(content = @Content(mediaType = "application/json"))
public void uploadFile(@RequestBody File file) { }

@ExampleObject
提供字段或参数的示例数据，通常与 @Schema、@RequestBody、@ResponseBody 一起使用。

@ExampleObject(name = "用户示例", value = "{\"id\": 1, \"name\": \"John Doe\"}")

@EnumSchema
用于枚举类型的字段，描述枚举的可选值。

@Schema(enumAsRef = true, description = "性别枚举")
private Gender gender;

4. 返回值和响应注解

这些注解用于描述 API 方法的返回类型或响应信息。

@ApiResponse
用于描述单个 API 的响应结果，例如 HTTP 状态码、响应体等。

@ApiResponse(responseCode = "200", description = "成功返回用户信息")

@ApiResponses
用于描述多个 API 响应结果（多个 HTTP 状态码的情况）。

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功返回用户信息"),
    @ApiResponse(responseCode = "404", description = "用户未找到")
})

@Response
用于描述返回类型，通常和 @Content 一起使用。

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

5. 其他注解

@SecurityRequirement
用于指定 API 端点的安全要求（如认证、授权）。

@Operation(summary = "获取受保护的资源", security = {@SecurityRequirement(name = "bearerAuth")})

@Link
定义资源之间的关联，通常用于描述响应中包含的相关链接。

@Link(name = "user-link", operationId = "getUserById", parameters = @LinkParameter(name = "id", expression = "$request.path.id"))

@Callback
定义回调 URL，当需要描述回调机制时使用。

@Callback(name = "callback", operation = @Operation(summary = "回调API"))

6. 全局级别注解

@OpenAPIDefinition
用于定义全局的 OpenAPI 配置信息，如标题、版本、服务器信息等。

@OpenAPIDefinition(
    info = @Info(
        title = "用户管理API",
        description = "管理用户的操作API",
        version = "v1.0.0"
    ),
    servers = {@Server(url = "http://localhost:8080", description = "本地开发环境")}
)

@Info
包含在 @OpenAPIDefinition 中，用于定义 API 的全局信息，如标题、描述、版本等。

@Info(title = "用户管理API", version = "1.0", description = "管理用户的API")

@Server
定义 API 文档中可用的服务器信息。

@Server(url = "http://localhost:8080", description = "开发环境")

7. 常用组合

组合注解示例：

import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.media.*;
import io.swagger.v3.oas.annotations.responses.*;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户相关操作的API")
public class UserController {

    @Operation(summary = "根据用户ID获取用户信息", description = "通过用户ID来获取用户详细信息")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "成功返回用户信息", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))),
        @ApiResponse(responseCode = "404", description = "用户未找到")
    })
    @GetMapping("/{id}")
    public User getUserById(@Parameter(description = "用户的唯一ID", example = "1") @PathVariable Long id) {
        return new User(id, "John Doe", "john.doe@example.com");
    }

    @Operation(summary = "创建新用户", description = "创建一个新的用户，返回创建的用户信息")
    @PostMapping
    public User createUser(@RequestBody @Schema(description = "用户实体") User user) {
        user.setId(100L); // 模拟生成用户ID
        return user;
    }
}

总结

这些注解大大丰富了自动生成的 OpenAPI 文档，可以为 API 提供清晰的参数、响应和模型描述，使得开发人员和使用者更容易理解 API 的用途和功能。