Swagger

Swagger简介

集成了接口测试和接口文档

快速使用

导入依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>2.9.2</version>
       </dependency>

       <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>2.9.2</version>
       </dependency>

当前最新的版本为2.10.5，容易出现无法访问ui的bug，所以用18年的2.9.2版本（目前使用最多的版本）

创建Swagger配置类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置Swagger的Bean实例
     * @return
     */
    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("作者姓名","团队地址","作者邮箱");

        return new ApiInfo("文档名称",
                "文档描述",
                "1.0",//版本信息
                "urn:tos",
                contact,
                "Apache 2.0",//开源版本信息
                "http://www.apache.org/licenses/LICENSE-2.0",//licence
                new ArrayList());
    }


}

配置类中为空则使用默认配置

在controller中创建测试接口

1
2
3
4
5
6
7
8
9
@RestController
@RequestMapping("/user/user")
public class UserController {

    @RequestMapping("hello")
    public String hello(){
        return "hello";
    }
}

访问localhost:8080/swagger-ui.html

Swagger 分组

在Swagger配置类中的Docket为一个分组文档，配置多个Docket即可分组

1
2
3
4
5
6
7
8
@Bean
  public Docket docket1 (){
      return new Docket(DocumentationType.SWAGGER_2).groupName("分组1");
  }
  @Bean
  public Docket docket2 (){
      return new Docket(DocumentationType.SWAGGER_2).groupName("分组2");
  }

分组结果：

Swagger 注解

==@Api()==
用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代
但是tags如果有多个值，会生成多个list

1
2
3
4
@Api(tags={"用户接口"})
@RestController
public class UserController {
}

==@ApiModel()==

用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略 

1
2
3
@ApiModel(value = "com.biancheng.auth.param.AddUserParam", description = "新增用户参数")
public class AddUserParam {
}

==@ApiModelProperty()==

用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用户名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;
 
      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}

==@ApiParam()==

用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填

1
2
3
4
5
@PostMapping("/user")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {
    System.err.println(param.getName());
    return new UserDto();
}

==@ApiOperation()==

用于方法；表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用） 

1
2
3
@ApiOperation(value="新增用户", notes="详细描述")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {
}

==@ApiResponse==

用于方法上，说明接口响应的一些信息；

==@ApiResponses==

组装了多个 @ApiResponse

1
2
3
4
@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })
@PostMapping("/user")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {
}

==@ApiIgnore()==

用于类或者方法上，可以不被swagger显示在页面上
比较简单, 这里不做举例

==@ApiImplicitParam()==

用于方法
表示单独的请求参数
==@ApiImplicitParams()==

用于方法，包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型

defaultValue-默认值

paramType–参数类型
example–举例说明

1
2
3
4
5
6
7
8
@ApiOperation("查询测试")
 @GetMapping("select")
 //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
 @ApiImplicitParams({
 @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
 @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
 public void select(){
 }