openapi3常用注解

OpenAPI3常用注解
OpenAPI3（也被称为Swagger）是一个用于描述和定义RESTful API的规范。

它使用YAML格式来描述API的路由、请求和响应等。

在OpenAPI3中，我们常常使用注解来添加更多的信息或设置，这些注解有助于自动生成API文档和进行代码生成。

以下是一些常用的OpenAPI3注解：
1.@ApiOperation: 用于描述一个特定的HTTP请求/响应。

它通常用于路由方
法上，提供简短的描述。

2.@ApiImplicitParams: 用于添加一组隐式的请求参数。

这些参数不会被显示
在API文档中，但会被包含在生成的代码中。

3.@ApiResponse: 用于描述一个特定的HTTP响应。

它通常用于路由方法上，
提供关于响应的详细信息。

4.@ApiModel: 用于描述一个模型类，该类将被用于生成请求和响应对象。

使
用这个注解可以为模型类添加额外信息，例如title、description等。

5.@ApiModelProperty: 用于描述模型类中的一个属性。

它可以添加额外的信
息，例如description、example等。

6.@ApiModelExample: 用于为模型类提供一个示例。

这个注解可以包含一个J
SON示例，该示例将被用于生成API文档。

7.@ApiRequestBody: 用于描述一个请求体。

它可以包含一个JSON示例，该示
例描述了请求体的结构。

8.@ApiResponses: 用于为路由方法提供多个响应描述。

这可以让你为不同的
HTTP状态码提供不同的描述。

9.@ApiIgnore: 用于指示某个路由或模型类不应被包括在生成的API文档中。

10.@ApiParam: 用于描述路由参数，例如查询参数或路径参数。

它可以添加额
外的信息，例如description、required等。

11.@ApiHeader: 用于描述HTTP头信息。

它可以添加额外的信息，例如descri
ption、required等。

12.@ApiProperty: 用于描述路由类中的一个属性。

它可以添加额外的信息，例
如description、example等。

13.@ApiHeaderMap: 用于描述路由参数的类型为Map的情况，它提供了键和值
的类型及默认值信息。

14.@ApiQueryParams: 用于定义路由的查询参数的结构体或者DTO（Data Tran
sfer Object）。

这个注解一般会与响应体一起使用，用来定义返回的数据结构。

15.@ApiSecurity: 用于定义API的安全方案，例如OAuth2等。

16.@ApiSecurityRequirement: 用于定义API的安全要求，例如需要某个特定
的角色或权限才能访问API。

这些是OpenAPI3中最常用的注解。

它们可以结合使用来生成详细的API文档和自动化的代码生成工具。