前言
在软件开发周期中,我们写完代码常常还要写文档,一方面给调用方提供调用文档,一方面也能归档。
其实,做开发的对于写文档这件事很是呵呵,占用了至少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
网友评论