在Spring Boot项目中使用Swagger文档

Posted by 代码无止境 on 2019-06-15

Spring Boot框架是目前非常流行的微服务框架,我们很多情况下使用它来提供Rest API。而对于Rest API来说很重要的一部分内容就是文档,Swagger为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证API文档的及时性将有很大的帮助。本文将使用Swagger 2规范的Springfox实现来了解如何在Spring Boot项目中使用Swagger,主要包含了如何使用Swagger自动生成文档、使用Swagger文档以及Swagger相关的一些高级配置和注解。

Swagger 简介

Swagger是一套基于OpenAPI规范构建的开源工具,可以帮助我们设计、构建、记录以及使用Rest API。Swagger主要包含了以下三个部分:

  • Swagger Editor:基于浏览器的编辑器,我们可以使用它编写我们OpenAPI规范。
  • Swagger UI:它会将我们编写的OpenAPI规范呈现为交互式的API文档,后文我将使用浏览器来查看并且操作我们的Rest API。
  • Swagger Codegen:它可以通过为OpenAPI(以前称为Swagger)规范定义的任何API生成服务器存根和客户端SDK来简化构建过程。

为什么要使用Swagger

现在有很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的工程师完成。在这种开发模式下,维持一份及时更新且完整的Rest API文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的,相信大家也都知道这种方式很难保证文档的及时性,这种文档久而久之也就会失去其参考意义,反而还会加大我们的沟通成本。而Swagger给我们提供了一个全新的维护API文档的方式,下面我们就来了解一下它的优点:

  • 代码变,文档变。只需要少量的注解,Swagger就可以根据代码自动生成API文档,很好的保证了文档的时效性。
  • 跨语言性,支持40多种语言。
  • Swagger UI呈现出来的是一份可交互式的API文档,我们可以直接在文档页面尝试API的调用,省去了准备复杂的调用参数的过程。
  • 还可以将文档规范导入相关的工具(例如SoapUI), 这些工具将会为我们自动地创建自动化测试。
    以上这些优点足以说明我们为什么要使用Swagger了,您是否已经对Swagger产生了浓厚的兴趣了呢?下面我们就将一步一步地在Spring Boot项目中集成和使用Swagger,让我们从准备一个Spring Boot的Web项目开始吧。

准备Spring Boot Web项目

在这一步我们将准备一个基础的Spring Boot的Web项目,并且提供后面所需要的所有API。

创建一个空的Spring Boot项目

您可以通过Spring Initializr页面生成一个空的Spring Boot项目,当然也可以下载springboot-pom.xml文件,然后使用Maven构建一个Spring Boot项目。项目创建完成后,为了方便后面代码的编写您可以将其导入到您喜欢的IDE中,我这里选择了Intelli IDEA打开。

添加依赖

由于创建的是一个Web项目,所以我们需要依赖Spring Boot的Web组件,只需要在pom.xml增加如下内容即可:

1
2
3
4
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

编写接口

1.首先我们创建三个包:cn.itweknow.sbswagger.controller、cn.itweknow.sbswagger.testcontroller以及cn.itweknow.sbswagger.model。
2.在controller包下新建UserController.java类,在testcontroller包下新建TestController.java类,在model包下新建User.java类。
3.UserController提供用户的增、删、改、查四个接口,TestContrller提供一个测试接口,这里粘上UserController.java的代码,其余代码可以查看源码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@RestController
@RequestMapping("/user")
public class UserController {
@PostMapping("/add")
public boolean addUser(@RequestBody User user) {
return false;
}
@GetMapping("/find/{id}")
public User findById(@PathVariable("id") int id) {
return new User();
}
@PutMapping("/update")
public boolean update(@RequestBody User user) {
return true;
}
@DeleteMapping("/delete/{id}")
public boolean delete(@PathVariable("id") int id) {
return true;
}
}

经过上面的步骤,我们已经拥有了五个接口,分别是:
1./user/add:新增用户。
2./user/find/{id}:根据id查询用户。
3./user/update:更新用户。
4./user/delete/{id}:根据id删除用户。
5./test/test:测试接口。
下面我们将通过集成Swagger2,然后为这5个Rest API自动生成接口文档。

添加Swagger2相关依赖

首先要做的自然是添加Swagger2所需要的依赖包:

1
2
3
4
5
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>

Java配置

Springfox提供了一个Docket对象,让我们可以灵活的配置Swagger的各项属性。下面我们新建一个cn.itweknow.sbswagger.conf.SwaggerConfig.java类,并增加如下内容:

1
2
3
4
5
6
7
8
9
10
11
12
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}

注意: @Configuration是告诉Spring Boot需要加载这个配置类,@EnableSwagger2是启用Swagger2,如果没加的话自然而然也就看不到后面的验证效果了。

验证

至此,我们已经成功的在Spring Boot项目中集成了Swagger2,启动项目后,我们可以通过在浏览器中访问http://localhost:8080/v2/api-docs来验证,你会发现返回的结果是一段JSON串,可读性非常差。幸运的是Swagger2为我们提供了可视化的交互界面SwaggerUI,下面我们就一起来试试吧。

集成Swagger UI

添加SwaggerUI相关依赖

和之前一样,集成的第一步就是添加相关依赖,在pom.xml中添加如下内容即可:

1
2
3
4
5
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

访问验证

其实就只需要添加一下依赖就可以了,我们重新启动一下项目,然后在浏览器中访问http://localhost:8080/swagger-ui.html 就可以看到如下的效果了。
avatar
可以看到虽然可读性好了一些,但对接口的表述还不是那么的清楚,接下来我们就通过一些高级配置,让这份文档变的更加的易读。

高级配置

文档相关描述配置

1.通过在控制器类上增加@Api注解,可以给控制器增加描述和标签信息。

1
2
@Api(tags = "用户相关接口", description = "提供用户相关的Rest API")
public class UserController

2.通过在接口方法上增加@ApiOperation注解来展开对接口的描述,当然这个注解还可以指定很多内容,我们在下面的相关注解说明章节中详细解释。

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

3.实体描述,我们可以通过@ApiModel和@ ApiModelProperty注解来对我们API中所涉及到的对象做描述。

1
2
3
4
5
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户id")
private int id;
}

4.文档信息配置,Swagger还支持设置一些文档的版本号、联系人邮箱、网站、版权、开源协议等等信息,但与上面几条不同的是这些信息不是通过注解配置,而是通过创建一个ApiInfo对象,并且使用Docket.appInfo()方法来设置,我们在SwaggerConfig.java类中新增如下内容即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfo(
"Spring Boot项目集成Swagger实例文档",
"我的博客网站:https://itweknow.cn,欢迎大家访问。",
"API V1.0",
"Terms of service",
new Contact("名字想好没", "https://itweknow.cn", "gancy.programmer@gmail.com"),
"Apache", "http://www.apache.org/", Collections.emptyList());
}

经过上面的步骤,我们的文档将会变成下图的样子,现在看起来就清楚很多了。
avatar

接口过滤

有些时候我们并不是希望所有的Rest API都呈现在文档上,这种情况下Swagger2提供给我们了两种方式配置,一种是基于@ApiIgnore注解,另一种是在Docket上增加筛选。

1.@ApiIgnore注解。
如果想在文档中屏蔽掉删除用户的接口(user/delete),那么只需要在删除用户的方法上加上@ApiIgnore即可。

1
2
@ApiIgnore
public boolean delete(@PathVariable("id") int id)

2.在Docket上增加筛选。Docket类提供了apis()和paths()两个方法来帮助我们在不同级别上过滤接口:

  • apis():这种方式我们可以通过指定包名的方式,让Swagger只去某些包下面扫描。
  • paths():这种方式可以通过筛选API的url来进行过滤。
    在集成Swagger2的章节中我们这两个方法指定的都是扫描所有,没有指定任何过滤条件。如果我们在我们修改之前定义的Docket对象的apis()方法和paths()方法为下面的内容,那么接口文档将只会展示/user/add和/user/find/{id}两个接口。
1
2
3
.apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller"))
.paths(Predicates.or(PathSelectors.ant("/user/add"),
PathSelectors.ant("/user/find/*")))

avatar

自定义响应消息

Swagger允许我们通过Docket的globalResponseMessage()方法全局覆盖HTTP方法的响应消息,但是首先我们得通过Docket的useDefaultResponseMessages方法告诉Swagger不使用默认的HTTP响应消息,假设我们现在需要覆盖所有GET方法的500和403错误的响应消息,我们只需要在SwaggerConfig.java类中的Docket Bean下添加如下内容:

1
2
3
4
5
6
7
8
9
10
11
12
.useDefaultResponseMessages(false)
.globalResponseMessage(RequestMethod.GET, newArrayList(
new ResponseMessageBuilder()
.code(500)
.message("服务器发生异常")
.responseModel(new ModelRef("Error"))
.build(),
new ResponseMessageBuilder()
.code(403)
.message("资源不可用")
.build()
));

添加如上面的代码后,如下图所示,您会发现在SwaggerUI页面展示的所有GET类型请求的403以及500错误的响应消息都变成了我们自定义的内容。
avatar

Swagger UI的使用

接口查看

SwaggerUI会以列表的方式展示所有扫描到的接口,初始状态是收缩的,我们只需要点击展开就好,而且会在左边标识接口的请求方式(GET,POST,PUT,DELETE等等)。
avatar

接口调用

如下图所示,点击接口展开后页面右上角的Try it out按钮后,页面会变成如图所示:
avatar
SwaggerUI会给我们自动填充请求参数的数据结构,我们需要做的只是点击Execute即可发起调用
avatar

Model

如下图所示,SwaggerUI会通过我们在实体上使用的@ApiModel注解以及@ApiModelProperty注解来自动补充实体以及其属性的描述和备注。
avatar

相关注解说明

在本章节中我将给出一些Swagger中常用的注解以及其常用的属性,并对其一一解释,方便您查看。

Controller相关注解

注解属性类型描述
tagsString[]控制器标签。
descriptionString控制器描述(该字段被申明为过期)。

接口相关注解

1.@ApiOperation: 可设置对接口的描述。

注解属性类型描述
valueString接口说明。
notesString接口发布说明。
tagsStirng[]标签。
responseClass<?>接口返回类型。
httpMethodString接口请求方式。

2.@ApiIgnore: Swagger文档不会显示拥有该注解的接口。
3.@ApiImplicitParams: 用于描述接口的非对象参数集。
4.@ApiImplicitParam: 用于描述接口的非对象参数,一般与@ApiImplicitParams组合使用。

注解属性描述
paramType查询参数类型,实际上就是参数放在那里。取值: path:以地址的形式提交数据,根据id查询用户的接口就是这种形式传参。 query:Query string的方式传参。 header:以流的形式提交。 form:以Form表单的形式提交。
dataType参数的数据类型。取值:Long,String
name参数名字。
value参数意义的描述。
required是否必填。取值:true:必填参数,false:非必填参数。

Model相关注解
1.@ApiModel: 可设置接口相关实体的描述。
2.@ApiModelProperty: 可设置实体属性的相关描述。

注解属性类型描述
valueString字段说明。
nameString重写字段名称。
dataTypeStirng重写字段类型。
requiredboolean是否必填。
exampleStirng举例说明。
hiddenboolean是否在文档中隐藏该字段。
allowEmptyValueboolean是否允许为空。
allowableValuesString该字段允许的值,当我们API的某个参数为枚举类型时,使用这个属性就可以清楚地告诉API使用者该参数所能允许传入的值。

结束语

在本教程中,我们学会了如何使用Swagger 2来生成Spring Boot REST API的文档。我们还研究了如何过滤API、自定义HTTP响应消息以及如何使用SwaggerUI直接调用我们的API。您可以在Github上找到本教程的完整实现,这是一个基于IntelliJ IDEA的项目,因此它应该很容易导入和运行,当然如果您想对本教程做补充的话欢迎发邮件给我 (gancy.programmer@gmail.com) 或者直接在GitHub上提交Pull Request。当然如果你觉得本篇文章还不错的话,顺手给个start,这是对我最好的鼓励。

转载说明:
“最初由 IBM developerWorks 中国网站发表,其网址是 http://www.ibm.com/developerworks/cn/***”。(注:IBM developerWorks 现已更名为 IBM Developer,> 其网址是 https://developer.ibm.com/cn 。)

ps:“学习不止,码不停蹄”,如果你喜欢我的文章,就关注我吧。

扫码关注“代码无止境”