一 Swagger由来和优势
现在多数的项目开发中,网站和移动端都需要进行数据交互和对接,这少不了使用REST编写API接口这种场景。 特别是不同开发小组协作时,就更需要以规范和文档作为标准和协作基础。
良好的文档可以减少沟通成本,达到事半功倍的效果。有时对一些API说明的理解比较模糊,总想着能直接验证一下自己的理解就好了,而不是需要去项目写测试代码来验证自己的想法。
即API文档应具备直接执行能力,这种能力类似word,wiki等是无法提供。
SwaggerUI就是这样一种利器,基于html+javascript实现,倾向于在线文档和测试,使用和集成十分简单,能容易地生成不同模块下的API列表, 每个API接口描述和参数、请求方法都
能定制并直接测试得到直观的响应数据。
二 Swagger常用注解使用
@Api:用在类上,说明该类的作用。
@ApiOperation:注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
三 Swagger搭建
1 添加依赖
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|