SpringBoot整合Swagger初探

当下的Web项目大都采用前后端分离+分布式微服务的架构。前后端分离式的开发中，前端开发人员要与后端开发人员协商通信接口，约定接口规范。因此对于开发人员来说能够维持一份及时更新且完整全面的API文档会大大提高开发效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式。

Swagger的特性

1. 代码发生更正时，文档也会自动的更正。
2. 跨语言，Swagger支持40种语言。
3. Swagger-UI可以提供一份交互式的API文档。
4. 可以与相关自动化测试软件结合使用。

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文档上。

1. 在控制器上使用@Api注解可以对控制器增加描述和标签信息

@Api(tags="中层互评控制器", description="中层互评相关API接口信息")
public class MiddleLevelEvaluationController
{}

注解属性	类型	描述
tags	String[]	为控制器添加标签
description	String	为控制器添加描述

2. 通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述，当然这个注解还可以指定很多内容。

@ApiOperation("新增用户接口")
@PostMapping("/add")
public boolean addUser(@RequestBody User user) 
{
    return false;
}

注解属性	类型	描述
value	String	接口说明
notes	String	接口发布说明
tages	String[]	标签
response	Class<?>	接口返回类型
httpMethod	String	请求的方式

3. 实体描述，可以通过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	该字段允许的值，一般用于可枚举的字段

4. 忽略API注解@ApiIgnore.