wagger的使用

一、 简介

最近做的一个前后端分离的项目，用到了swagger，在次记录一下swagger的基本使用方法。
首先介绍一下swagger的作用，

1、方便的管理代码文档

一个比较大的项目接口会有非常多，如果用world写接口文档会是一件非常痛苦的事情，而且写文档对大多数程序员来说是不擅长也不喜欢的。swagger能够将接口文档与代码相结合，形成和后期管理都比较方便。

2、有利于前后端交互联调

swagger提供来一个ui界面，所形成的接口文档都会在页面显示，包括接口路径，接口名称，输入输出参数，示例参数等等。后端开发可以很方便的用来做接口单元测试，前端开发也可以很清晰的从文档获得对应API的调用。

二、使用方法

1、项目依赖

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.0.RELEASE</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2、常用注解

注解	描述	作用域
@Api	将类标记为Swagger资源。	类或接口
@ApiImplicitParam	表示API操作中的单个参数。	方法
@ApiImplicitParams	一个包装器，允许列出多个@ApiImplicitParam对象。	方法
@ApiModel	提供有关Swagger模型的其他信息。	类
@ApiModelProperty	添加和操作模型属性的数据。	属性
@ApiOperation	描述针对特定路径的操作或通常是HTTP方法。	方法
@ApiParam	为操作参数添加其他元数据。	参数
@ApiResponse	描述操作的可能响应。	方法
@ApiResponses	一个包装器，允许列出多个@ApiResponse对象。	方法

3、说明举例

3、1 @Api

@Api：放在 请求的类上，与@Controller并列，说明的请求类的用下，如用户登录类，订单类等。
tags=“说明该类的作用”
vlue=“该参数没什么意义，所以不需要配置”
属性值：

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径
position	如果配置多个Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true ，将在文档中隐藏

样例：

@Api(tags="测试")
@Controller
public class TestController {
}

3、2 @ApiImplicitParam和@ApiImplicitParams

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
样例：

    @ApiOperation(value="用户注册",notes="用户名，密码必填")
    @ApiImplicitParams({
    @ApiImplicitParam(name="userName",value="用户名称",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
    })
    @PostMapping("/login")
    public JsonResult register(@RequestParam String userName, @RequestParam String password,@RequestParam Integer age){
    ...
    return JsonResult.ok(map);
}

3、3 @ApiModel和@ApiModelProperty

@ApiModel：用于响应类上，表示一个返回响应数据的信息 （这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候） @ApiModelProperty：用在属性上，描述响应类的属性

样例：

    @ApiModel(description= "返回响应数据")
    public class RestMessage implements Serializable{
        @ApiModelProperty(value = "是否成功")
        private boolean success=true;
        @ApiModelProperty(value = "返回对象")
        private Object data;
        @ApiModelProperty(value = "错误编号")
        private Integer errCode;
        @ApiModelProperty(value = "错误信息")
        private String message;
           
        /* getter/setter */
}

3、4 @ApiOperation

@ApiOperation：“用在请求的方法上，说明方法的作用”

属性：

属性名称	备注
value	说明方法的作用
notes	方法的备注说明

样例：

   @GET
    @ApiOperation(value = "查找用户",
            notes = "查找用户",
            response = User.class,
            responseContainer = "List")
public Response findUser(...) { ... }