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.

巴特西

SpringBoot整合Swagger初探

Swagger的特性

Swagger与SpringBoot结合

Swagger相关注解

最新文章

热门文章