Swagger2简单使用教程

Swagger2简单使用教程
1、简介
​ Swagger是为了解决企业中接口（api）中定义统一标准规范的文档生成工具。很多采用前后端分离的模式，前端只负责调用接口，进行渲染，前端和后端的唯一联系，变成了API接口。因此，API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架，而且swagger可以模拟http请求调用。

2、常用注解与示例
@Api（）用于类：表示标识这个类是swagger的资源

@Api(“用于类”)
@Controller
public class swaggerTest(){
}
1
2
3
4
@ApiOperation（）用于方法：表示一个http请求的操作

@Api(“ApiOperation测试”)
@Controller
public class swaggerTest(){
@ApiOperation(value = “apiOperationTest”, notes = “apiOperation测试”)
public void apiOperationSwaggerTest(){
}
}
1
2
3
4
5
6
7
@ApiParam（）：用于方法，参数，字段说明：表示对参数的添加元数据（说明或是否必填等）

@Api(“ApiParam测试”)
@Controller
public class swaggerTest(){
@ApiOperation(value = “apiOperationTest”, notes = “apiOperation测试”)
public void apiOperationTest(@ApiParam(name = “id”, value = “1”, required = true) Integer id){
}
}
1
2
3
4
5
6
7
@ApiModel（）用于类：表示对类进行说明，用于参数用实体类接收

@ApiModel(description = “实体类”, value = “实体类”)
public class City implements Serializable {

}
1
2
3
4
@ApiModelProperty（）用于方法，字段：表示对model属性的说明或者是数据操作更改

@ApiModel(description = “实体类”, value = “实体类”)
public class City implements Serializable {
@ApiModelProperty(name = “id”, value = “编号”, required = false, exmaple = “1”)
private int id;
}
1
2
3
4
5
@ApiIgnore（）用于类，方法，方法参数：表示这个方法或者类被忽略

@ApiIgnore
@Api(tags = {“Xxx控制类”})
@RestController
@RequestMapping("/xxx")
public class XxxController {

}
1
2
3
4
5
6
7
@ApiImplicitParam（）用于方法：表示单独的请求参数

@ApiImplicitParams（）用于方法，包含多个@ApiImplicitParam

@Api(“测试1”)
@Controller
public class swaggerTest(){
@ApiOperation(value = “apiOperationTest”, notes = “apiOperation测试”)
@ApiImplicitParams({@ApiImplicitParam(name = “id”, value = “id”, required = true, dataType = “Integer”, paramType = “query”),
@ApiImplicitParam(name = “name”, value = “name”, required = true, dataType = “String”, paramType = “query”)
})
public void apiOperationSwaggerTest(Integer id, String name){
}
}