SpringBoot整合Swagger初探
当下的Web项目大都采用前后端分离+分布式微服务的架构。前后端分离式的开发中,前端开发人员要与后端开发人员协商通信接口,约定接口规范。因此对于开发人员来说能够维持一份及时更新且完整全面的API文档会大大提高开发效率。传统意义上的文档都是后端开发人员手动编写的,相信大家也都知道这种方式很难保证文档的及时性,这种文档久而久之也就会失去其参考意义,反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式。
Swagger的特性
- 代码发生更正时,文档也会自动的更正。
- 跨语言,Swagger支持40种语言。
- Swagger-UI可以提供一份交互式的API文档。
- 可以与相关自动化测试软件结合使用。
Swagger与SpringBoot结合
准备好SpringBoot的基本环境后,通过Maven导入Swagger依赖。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
Swagger-UI Maven坐标,使用Swagger-UI可以在项目中可视化的展示API文档。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
在SpringBoot项目中配置Swagger
@Configuration
@EnableSwagger2
public class BeansConfig
{
@Bean
public Docket api()
{
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.apiInfo(new ApiInfo("文档标题", "文档的描述", "文档版本号", "Terms",
new Contact("姓名", "个人主页", "邮箱"),
"Apache", "http://www.apache.org", Collections.emptyList()));
}
}
这样你就可以在你的项目中使用Swagger了,项目启动之后,在浏览器地址栏输入localhost:(服务端口号)/swagger-ui.html
就可以可视化的查看项目中的API接口信息。
Swagger相关注解
同时你也可以使用相关注解对一些API接口进行解释说明,这些解释说明最终会显示在API文档上。
- 在控制器上使用
@Api
注解可以对控制器增加描述和标签信息
@Api(tags="中层互评控制器", description="中层互评相关API接口信息")
public class MiddleLevelEvaluationController
{}
注解属性 | 类型 | 描述 |
---|---|---|
tags | String[] | 为控制器添加标签 |
description | String | 为控制器添加描述 |
- 通过在接口方法上增加
@ApiOperation
注解来展开对接口的描述,当然这个注解还可以指定很多内容。
@ApiOperation("新增用户接口")
@PostMapping("/add")
public boolean addUser(@RequestBody User user)
{
return false;
}
注解属性 | 类型 | 描述 |
---|---|---|
value | String | 接口说明 |
notes | String | 接口发布说明 |
tages | String[] | 标签 |
response | Class<?> | 接口返回类型 |
httpMethod | String | 请求的方式 |
- 实体描述,可以通过
ApiModel
和@ApiModelProperty
对API中所涉及的实体对象进行描述
@ApiModel("用户实体")
public class User
{
@ApiModelProperty("用户 id")
private int id;
}
@ApiModelProperty
注解属性
注解属性 | 类型 | 描述 |
---|---|---|
value | String | 字段说明 |
name | String | 重写字段名称 |
dateType | String | 重写字段类型 |
required | boolean | 是否必填 |
example | String | 举例说明 |
hidden | boolean | 是否在文档中隐藏该字段 |
allowEmptyValue | boolean | 是否允许为空 |
allowableValues | String | 该字段允许的值,一般用于可枚举的字段 |
- 忽略API注解
@ApiIgnore
.