背景
Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已经形成一个生态圈,能够管理API的整个生命周期,从设计、文档到测试与部署。Swagger有几个重要特性:
- 代码侵入式注解
- 遵循YAML文档格式
- 非常适合三端(PC、iOS及Android)的API管理,尤其适合前后端完全分离的架构模式。
- 减少没有必要的文档,符合敏捷开发理念
- 功能强大
Swagger拥有众多不同语言和平台的开源实现与工具,主要有:
- Swagger UI,基于Swagger-compliant API的一套可以展示优美文档的Web应用。
- Swagger Editor,一款以YAML格式编辑与管理API的工具,同时支持JSON格式的文档描述。
- Swagger-Core,Swagger的Java/Scala实现,并已集成 JAX-RS (Jersey, Resteasy, CXF…), Servlets与Play Framework。
- Swagger-JS,Swagger的Javascript版本实现。
API的注解
对于API的设计,一般倾向于将功能相同的API归集为一组。在Spring Boot中,利用Controller来实现,每个Controller里包含若干个REST API,而每个API都有输入及输出值。所以swagger对API的注解也是参照这个层级来划分与实现的。其逻辑结果如下图:
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
@Api注解
该注解将一个Controller(Class)标注为一个swagger资源(API)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。
属性名称 | 备注 |
---|---|
tags | API分组标签。具有相同标签的API将会被归并在一组内展示。 |
value | 如果tags没有定义,value将作为Api的tags使用 |
description | API的详细描述 |
position | 如果配置多个Api 想改变显示的顺序位置 |
hidden | 配置为true 将在文档中隐藏 |
案例:
@RestController
@RequestMapping(value = "/")
@Api("登录管理") // == @Api(value="登录管理")
public class LoginController extends BaseController {
@ApiOperation注解
在指定的(路由)路径上,对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。
属性名称 | 备注 |
---|---|
value | 对操作的简单说明,长度为120个字母,60个汉字。 |
notes | 对操作的详细说明。 |
httpMethod | HTTP请求的动作名,可选值有:“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。 code |
code | http的状态码 默认 200 |
response | 方法返回值的类型 |
案例:
@GetMapping(value = "/login", produces = {"application/json;charset=UTF-8"})
@ApiOperation(value = "登录方法", notes = "登录方法", response = ResponseBean.class)
public ResponseBean login(@RequestParam String loginName, @RequestParam String password,HttpServletRequest request) {
@ApiImplicitParam注解
对API的单一参数进行注解。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。
属性名称 | 备注 |
---|---|
name | 参数名称 |
value | 参数的简短描述 |
dataType | 参数类型,可以为类名,也可以为基本类型(String,int、boolean等) |
paramType | 参数的传入类型,(参数放在哪里) |
required | 参数是否必须传 |
defaultValue | 参数的默认值 |
Swagger 中 paramType的值包括如下5项:
- header–>请求参数的获取:@RequestHeader(代码中接收注解)
- query–>请求参数的获取:@RequestParam(代码中接收注解)
- path–>请求参数的获取:@PathVariable(代码中接收注解)
- body–>请求参数的获取:@RequestBody(代码中接收注解)
- form(不常用)
@ApiImplicitParams注解
注解ApiImplicitParam的容器类,以数组方式存储。
案例:
@GetMapping(value = "/login", produces = {"application/json;charset=UTF-8"})
@ApiOperation(value = "登录方法", notes = "登录方法", response = ResponseBean.class)
@ApiImplicitParams({
@ApiImplicitParam(name = "loginName", value = "用户登录名称", required = true, dataType = "String"),
@ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String")
})
public ResponseBean login(@RequestParam String loginName, @RequestParam String password,HttpServletRequest request) {
@ApiParam注解
增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有:
属性名称 | 备注 |
---|---|
required | 是否为必传参数 |
value | 参数简短说明 |
@ApiResponse注解
描述一个操作可能的返回结果。当REST API请求发生时,这个注解可用于描述所有可能的成功与错误码。可以用,也可以不用这个注解去描述操作的返回类型,但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型,那么需要分别定义返回值,并将返回类型进行关联。但Swagger不支持同一返回码,多种返回类型的注解。注意:这个注解必须被包含在@ApiResponses注解中。
属性名称 | 备注 |
---|---|
code | HTTP请求返回码。 |
message | 更加易于理解的文本消息 |
response | 返回类型信息,必须使用完全限定类名,比如“com.czx.Person.class” |
responseContainer | 如果返回类型为容器类型,可以设置相应的值。有效值为 “List”, “Set” or “Map”,其他任何无效的值都会被忽略。 |
@ApiResponses注解
注解@ApiResponse的包装类,数组结构。即使需要使用一个@ApiResponse注解,也需要将@ApiResponse注解包含在注解@ApiResponses内。
案例:
@ApiOperation(value = "登录方法", notes = "登录方法", response = ResponseBean.class)
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
public ResponseBean login(@RequestParam String loginName, @RequestParam String password,HttpServletRequest request) {
Model的注解
对于Model的注解,Swagger提供了两个:@ApiModel及@ApiModelProperty,分别用以描述Model及Model内的属性。
@ApiModel
提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内,所有的类将自动被内省(introspected),但利用这个注解可以做一些更加详细的model结构说明。主要属性有:
属性名称 | 备注 |
---|---|
value | model的别名,默认为类名 |
description | model的详细描述 |
@ApiModelProperty
对model属性的注解,主要的属性值有:
属性名称 | 备注 |
---|---|
value | 属性简短描述 |
example | 属性的示例值 |
required | 是否为必须值 |
案例:
@ApiModel(value="User对象", description="系统用户表")
public class User extends Model<User> {
@ApiModelProperty(value = "唯一编码")
private Integer id;
@ApiModelProperty(value = "创建人")
private Integer createBy;
@ApiModelProperty(value = "创建时间 : 创建时间")
private Date createDate;
@ApiModelProperty(value = "更新人 : 更新人")
private Integer updateBy;
}
关于Token问题
考虑到安全的问题,每次请求API需要对用户进行验证与授权。目前主流的验证方式采用请求头部(request header)传递token,即用户登录之后获取一个token,然后每次都使用这个token去请求API。如果想利用swagger-UI进行API测试,必须显式为每个需要验证的API指定token参数。这时可以为每个操作添加一个注解@ApiImplicitParams,具体代码如下:
@ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})