swagger 通过注解表明该接口会生成文档, 包括接口名, 请求方法, 参数, 返回信息的等等.
swagger2 常用注解:
@API: 修饰整个类, 描述 Controller 的作用
@ApiOperation: 描述一个类的一个方法, 或者说一个接口
@ApiParam: 单个参数描述
@ApiModel: 用对象来接收参数
@ApiProperty: 用对象接收参数时, 描述对象的一个字段
@ApiResponse:HTTP 响应其中 1 个描述
@ApiResponses:HTTP 响应整体描述
@ApiIgnore: 使用该注解忽略这个 API
@ApiError : 发生错误返回的信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParams: 多个请求参数
注解对应参数解析:
@API: 用在请求的类上, 表示对类的说明
- tags="说明该类的作用, 可以在 UI 界面上看到的注解"
- value="该参数没什么意义, 在 UI 界面上也看到, 所以不需要配置"
@ApiOperation: 用在请求的方法上, 说明方法的用途, 作用
- value="说明方法的用途, 作用"
- notes="方法的备注说明"
@ApiImplicitParams: 用在请求的方法上, 表示一组参数说明
@ApiImplicitParam: 用在 @ApiImplicitParams 注解中, 指定一个请求参数的各个方面
name: 参数名
value: 参数的汉字说明, 解释
required: 参数是否必须传
paramType: 参数放在哪个地方
. header --> 请求参数的获取:@RequestHeader
. query --> 请求参数的获取:@RequestParam
. path(用于 restful 接口)--> 请求参数的获取:@PathVariable
- . body(不常用)
- . form(不常用)
dataType: 参数类型, 默认 String, 如果参数为整型, 针对 dataType="Integer",swagger2 似乎无效, 只能用 int
defaultValue: 参数的默认值
@ApiResponses: 用在请求的方法上, 表示一组响应
@ApiResponse: 用在 @ApiResponses 中, 一般用于表达一个错误的响应信息
code: 数字, 例如 400
message: 信息, 例如 "请求参数没填好"
response: 抛出异常的类
@ApiModel: 用于响应类上, 表示一个返回响应数据的信息
(这种一般用在 post 创建的时候, 使用 @RequestBody 这样的场景,
请求参数无法使用 @ApiImplicitParam 注解进行描述的时候)
@ApiModelProperty: 用在属性上, 描述响应类的属性
代码请参考我的 GitHub: https://github.com/yaoshuangqi/maven-parent.git
来源: http://www.bubuko.com/infodetail-3446914.html