携手创作，共同成长！这是我参与「掘金日新计划 · 8 月更文挑战」的第29天，点击查看活动详情
概述
公司使用swagger生成接口文档，然后发布到YAPI等接口管理平台中。所以这就要求项目组的各个同事定义的swagger注释有一定的规范，哪些注解的属性是必填的，哪些注解的内容该如何指定，而不是随心所欲，这样生成出来的接口文档才会漂亮，有效。所以本篇文章主要讲解我们公司的swagger注解规范，希望达到的目标是足够极简、足够有效。
接口规范要求
- 需要描述清楚接口的含义，作用，适用场景和注意事项等。
- 请求参数逐个描述清楚，包括它的参数类型，是body、query、path等，参数数据类型，比如string还是int, 参数是否必填，接口描述中的参数数量和接口实际的参数数量对齐一致，不能多，也不能少。
- 接口返回的报文需要描述清楚，包括报文的含义、数据类型、是否必须返回等。
- 在描述含义的时候，涉及到枚举，比如状态、规则类型等，需要在列清楚枚举和对应的含义。
这些接口规范，其实可以体现在swagger的注解上，所以我们需要有一个swagger注解的最佳实践，让大家花最小代价描述清楚接口的格式，然后可以发布到接口管理平台如YAPI中。
注解依赖
我们公司采用的swagger3的依赖，但是为了兼容，我们依然使用的是swagger-annotations:1.5.24版本的注解。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
注解最佳实践
类相关注解
@Api
说明：用在请求的类上，表示对类的说明
| 属性 | 说明 | 是否必填 | 示例 |
|---|---|---|---|
| tags | 类的标签，可以多个，会展示在UI上，建议使用模块，因为发布到YAPI中会作为分类。 | 是 | tags = "模型管理模块"tags = {"模型管理模块", "指标管理模块"} |
实例：
展示：
方法相关注解
方法上的注解是由多个swagger注解组合而成。
@ApiOperation
说明：用在请求的方法上，说明方法的用途、作用。
| 属性 | 说明 | 是否必填 | 示例 |
|---|---|---|---|
| value | 说明方法的用途、作用 | 是 | value = "模型列表查询" |
| tags | 方法的标签，可以标记这个方法引入的版本，发布到YAPI会有标签属性，方便过滤 | 是 | tags = {"7.24.0-9"} |
@ApiImplicitParams
说明：用来说明请求参数的含义集合。
| 属性 | 说明 | 是否必填 | 示例 |
|---|---|---|---|
| value | 是@ApiImplicitParam注解的列表，一个ApiImplicitParam表示一个请求参数 | 是 | @ApiImplicitParams({@ApiImplicitParam(name = "channelId", required = false, value = "渠道Id")}） |
@ApiImplicitParam
说明：用来说明请求的每个参数的含义，每个请求参数和方法的入参必须一一对象。
| 属性 | 说明 | 是否必填 | 示例 |
|---|---|---|---|
| name | 参数名，必须和方法的参数保持一样，否则swagger会报错 | 是 | name="username" |
| value | 参数的说明解释 | 是 | value = "所属机构" |
| required | 表明该参数是否必须传入数据，默认为false | 是 | required = true |
| paramType | 参数的类型，可选的枚举如下：- path：参数是在路径中 |
- query：参数是查询参数
- body: 参数是请求体中
- header：参数是在请求头中
- form：参数表单格式 | 是 | paramType = "query" | | dataTypeClass | 参数的数据类型, 不写会有很多警告日志 | 是 | dataTypeClass=String.class | | defaultValue | 默认值 | 否 | defaultValue="aa" | | example | 例子 | 否 | example="aa" |
实例：
数据模型注解
数据模型注解主要用来阐述接口的返回内容以及接口的请求参数对象的内容信息。
@ApiModel
说明：用于数据模型上，表示数据模型的信息
| 属性 | 说明 | 是否必填 | 示例 |
|---|---|---|---|
| value | 数据模型名称 | 是 | value="用户对象" |
| description | 数据模型详细描述，一般不用填写 | 否 |
@ApiModelProperty
说明：数据模型的属性信息
| 属性 | 说明 | 是否必填 | 示例 |
|---|---|---|---|
| value | 模型属性的描述 | 是 | value="用户名" |
| required | 是否必须有这个属性，默认false | 是 | |
| hidden | 是否隐藏该属性，默认为false，主要有些时候某个接口不需要这个属性返回，可以设置为true | 否 |
实例：
使用注意事项
- 尽量每个接口都有自己的数据模型，不要把所有的接口的返回都冗余到一个数据模型中，这样会导致接口很冗余混乱。
- swagger注解的dataType需要写清楚，不然会有很多warn警告。
- swagger注解中的ApiImplicitParam和方法中的参数保持一致，不然会报错，导致swagger页面无法展示。
\
