使用自定义注释增强 Swagger 文档

Swagger 是一种基于 OpenAPI 规范的 API 开发工具集合，可以自动生成文档、客户端 SDK 和测试代码等。在使用 Swagger 自动生成文档时，我们可以通过在代码中添加注释来增强文档的说明和描述，这些注释被称为 Swagger 注解。

基本注解

Swagger 提供了很多注解，用于描述 API 的信息，比如 API 名称、请求方法、请求参数、请求头、返回结果等。下面是一些常用的注解：

@Api

用于描述整个 API 的信息，包括 API 标题、描述、版本号等。

/**
 * @Api(tags = "User", description = "用户接口")
 */

@ApiOperation

用于描述一个 API 的操作信息，包括 API 的请求方法、请求路径、请求参数、请求头、返回结果等。

/**
 * @ApiOperation(value = "提交用户信息", notes = "提交用户信息到服务器")
 * @ApiImplicitParams({
 *     @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "string", paramType = "query"),
 *     @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "string", paramType = "query")
 * })
 * @ApiResponse(code = 200, message = "OK", response = Result.class)
 */

@ApiImplicitParam

用于描述 API 的请求参数信息，包括参数名称、参数类型、是否必需等。

/**
 * @ApiImplicitParams({
 *     @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "string", paramType = "query"),
 *     @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "string", paramType = "query")
 * })
 */

@ApiModel

用于描述一个数据模型的信息，包括模型名称、模型描述、属性列表等。

/**
 * @ApiModel(value = "UserModel", description = "用户数据模型")
 */
public class User {
    ...
}

@ApiModelProperty

用于描述一个数据模型的属性信息，包括属性名称、属性描述、属性数据类型等。

/**
 * @ApiModelProperty(name = "username", value = "用户名", required = true, example = "John")
 */
private String username;

自定义注解

除了使用 Swagger 自带的注解外，我们还可以自定义一些注解，用于描述 API 的特定信息。比如：

@ApiAuth

用于描述 API 的授权信息，包括授权类型、授权参数等。

/**
 * @ApiAuth(type = "Bearer", name = "Authorization")
 */

@ApiRateLimit

用于描述 API 的速率限制信息，包括速率限制类型、速率限制参数等。

/**
 * @ApiRateLimit(type = "IP", limit = "1000/hour")
 */

结论

使用自定义注解可以让 Swagger 自动生成的文档更加清晰、易于理解。除了上面介绍的几种注解外，Swagger 还提供了很多其他的注解，可以根据实际需求进行选择和使用。