前言
在软件开发周期中，我们写完代码常常还要写文档，一方面给调用方提供调用文档，一方面也能归档。
其实，做开发的对于写文档这件事很是呵呵，占用了至少40%的开发时间，而且每当代码有调整，还得记得去修改对应的文档。
那么，springboot有没有哪种方法可以帮助我们自动生成文档呢，这样能解决我们开发人员的痛点。
本章，我们就来介绍Swagger2这个东东，使用后你会爱上它的。
好处：
- 自动生成文档，代码写完，文档即完成
- 无需复杂的配置，简单易用
Swagger2常用注解
@Api()用于类；
表示标识这个类是swagger的资源
tags：表示说明
value：也是说明，可以使用tags替代
@Api(value="测试controller",tags={"测试接口"})
@RestController
public class Swagger2Controller {
}
@ApiOperation()用于方法；
表示一个http请求的操作
value：用于方法描述
notes： 用于提示内容
tags： 可以重新分组
@ApiOperation(value="获取列表",tags={"获取列表信息"},notes="列表")
@GetMapping("/getList")
public int getList() {
return 1;
}
@ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
name：参数名
value：参数说明
required：是否必填
@ApiOperation("查询2")
@GetMapping("/query")
public Long query(@ApiParam(name = "id", value = "id", required = true) Long id, @ApiParam(name = "name", value = "名称", required = true) String name) {
return id;
}
@ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
value：表示对象名
description：描述
@ApiModel(value="Person对象",description="用户对象Person")
public class Person {
}
@ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
value：字段说明
name：重写属性名字
dataType：重写属性类型
required：是否必填
example：举例说明
hidden：隐藏
public class Person {
@ApiModelProperty(value = "名称", name = "name", example = "张三", required = true)
private String name;
}
@ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
@ApiIgnore()
@ApiOperation("隐藏")
@ApiParam(name = "Person对象", value = "传入json格式", required = true)
@GetMapping("/hideFunc")
public Person hideFunc(@RequestBody Person person) {
return person;
}
@ApiImplicitParam() 用于方法
表示单独的请求参数
name：参数ming
value：参数说明
dataType：数据类型
paramType：参数类型
example：举例说明
@ApiOperation("详情")
@ApiImplicitParam(name = "id", value = "id", required = true, dataType = "long", paramType = "query")
@GetMapping("/getInfoById")
public Long getInfoById(Long id) {
return id;
}
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
@ApiOperation("查询")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "id", dataType = "long", paramType = "query"),
@ApiImplicitParam(name = "name", value = "名称", dataType = "string", paramType = "query", example = "张三")
})
@GetMapping("/queryList")
public Long queryList(Long id, String name) {
return id;
}
更多注解及使用方式请查看
Swagger2配置
@Configuration
@EnableSwagger2
public class Swagger2Config {
//http://127.0.0.1:8080/swagger-ui.html#/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger自动构建文档")
.description("简单使用swagger2")
.version("1.0.0")
.build();
}
}
文档查看地址
http://127.0.0.1:8080/swagger-ui.html#/
项目地址
https://github.com/MrCoderStack/SpringBootDemo/tree/master/sb-swagger2
请关注我的订阅号
