SpringBoot学习笔记：Swagger实现文档管理
Swagger
Swagger是一个规范且完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger的目标是对REST API定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。
集成Swagger管理API文档
项目中集成Swagger
首先是添加swagger的依赖：
<!--swagger-spring-boot-starter -->
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
接着，在启动类中添加@EnableSwagger2Doc注解开启Swagger，如下：
@EnableSwagger2Doc
@SpringBootApplication
public class Application { public static void main(String[] args) {
SpringApplication.run(CodeHelperApplication.class, args);
}
}
使用Swagger生成文档
Swagger通过注解来生成对应的API，在接口上我们需要加上各种注解来描述这个接口，如
@ApiOperation(value = " 查找城镇列表 ")
@ApiResponses({@ApiResponse(code = 200,message = "OK",response = String.class)})
@RequestMapping(value = "getTownInfoList.do", method = RequestMethod.POST)
public List<String> getTownInfoList() {
try {
return studentMapper.getListGroup("stu_town");
} catch (Exception e) {
e.printStackTrace();
}
return null;
}
在这里我们使用到了两个注解：
- @ApiOperation用在方法上，说明方法的作用，添加notes属性可以详细描述接口信息。
- @ApiResponses用在方法上，说明接口响应的一些信息；@ApiResponses封装了多个@ApiResponse，来为不同的响应码设置不同响应信息。
在线测试接口
通过 服务器地址:port/swagger-ui.html 来访问Swagger服务，其界面如下：
找到刚刚描述的方法，可以查看接口详情，以及尝试接口调用。
Swagger注解
本节主要描述一些常用的生成接口文档的注解，上面介绍过的就不说了
@Api
用在类上，说明该类的作用.
@Api(tags = {"学生信息接口"})
@RestController
public class StudentController {
...
}
@ApiModel
用在类上，表示对参数类进行说明。
@ApiModel(value = "com.ms.qiandao.model.StudentModel",description = "新增用户参数")
public class StudentModel {
private Integer stu_id;
private String stu_name;
private String stu_sex;
...
}
@ApiModedlProperty
用在字段上，表示对参数类中的字段进行说明。
@ApiModel(value = "com.ms.qiandao.model.StudentModel",description = "新增用户参数")
public class StudentModel {
@ApiModelProperty(value = "学生ID")
private Integer stu_id;
@ApiModelProperty(value = "学生姓名")
private String stu_name;
@ApiModelProperty(value = "学生性别")
private String stu_sex;
...
}
@ApiParam
用于对Controller方法中的参数进行说明。
@RequestMapping("cancel.do")
public RegisterCode getById(@ApiParam(value = "学生id",required = true) Integer id) {
...
}
@ApilmplicitParam和@ApilmplicitParams
用于方法上，为单独的请求参数进行说明，和@ApiParam差不多，只不过是写在方法上面。
参考资料
- 《Spring Cloud微服务入门、实战与实践》
- https://swagger.io/tools/swagger-ui/