Spring Boot 框架是目前非常流行的微服务框架,我们很多情况下使用它来提供 Rest API。而对于 Rest API 来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了解如何在 Spring Boot 项目中使用 Swagger,主要包含了如何使用 Swagger 自动生成文档、使用 Swagger 文档以及 Swagger 相关的一些高级配置和注解。
Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分:
当下很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的工程师完成。在这种开发模式下,维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的,相信大家也都知道这种方式很难保证文档的及时性,这种文档久而久之也就会失去其参考意义,反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式,下面我们就来了解一下它的优点:
以上这些优点足以说明我们为什么要使用 Swagger 了,您是否已经对 Swagger 产生了浓厚的兴趣了呢?下面我们就将一步一步地在 Spring Boot 项目中集成和使用 Swagger,让我们从准备一个 Spring Boot 的 Web 项目开始吧。
在这一步我们将准备一个基础的 Spring Boot 的 Web 项目,并且提供后面所需要的所有 API。
您可以通过 Spring Initializr 页面 生成一个空的 Spring Boot 项目,当然也可以下载 springboot-pom.xml 文件,然后使用 Maven 构建一个 Spring Boot 项目。项目创建完成后,为了方便后面代码的编写您可以将其导入到您喜欢的 IDE 中,我这里选择了 Intelli IDEA 打开。
由于创建的是一个 Web 项目,所以我们需要依赖 Spring Boot 的 Web 组件,只需要在 pom.xml 增加如下内容即可:
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
@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; } }
经过上面的步骤,我们已经拥有了五个接口,分别是:
下面我们将通过集成 Swagger2,然后为这 5 个 Rest API 自动生成接口文档。
首先要做的自然是添加 Swagger2 所需要的依赖包:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
Springfox 提供了一个 Docket 对象,让我们可以灵活的配置 Swagger 的各项属性。下面我们新建一个 cn.itweknow.sbswagger.conf.SwaggerConfig.java 类,并增加如下内容:
@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,下面我们就一起来试试吧。
和之前一样,集成的第一步就是添加相关依赖,在 pom.xml 中添加如下内容即可:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
其实就只需要添加一下依赖就可以了,我们重新启动一下项目,然后在浏览器中访问 http://localhost:8080/swagger-ui.html 就可以看到如下的效果了:
可以看到虽然可读性好了一些,但对接口的表述还不是那么的清楚,接下来我们就通过一些高级配置,让这份文档变的更加的易读。
@Api
注解,可以给控制器增加描述和标签信息。 @Api(tags = "用户相关接口", description = "提供用户相关的 Rest API") public class UserController
@ApiOperation
注解来展开对接口的描述,当然这个注解还可以指定很多内容,我们在下面的相关注解说明章节中详细解释。 @ApiOperation("新增用户接口") @PostMapping("/add") public boolean addUser(@RequestBody User user) { return false; }
@ApiModel
和 @ApiModelProperty
注解来对我们 API 中所涉及到的对象做描述。 @ApiModel("用户实体") public class User { @ApiModelProperty("用户 id") private int id; }
Docket.appInfo()
方法来设置,我们在 SwaggerConfig.java 类中新增如下内容即可。 @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()); }
经过上面的步骤,我们的文档将会变成下图的样子,现在看起来就清楚很多了。
有些时候我们并不是希望所有的 Rest API 都呈现在文档上,这种情况下 Swagger2 提供给我们了两种方式配置,一种是基于 @ApiIgnore
注解,另一种是在 Docket 上增加筛选。
@ApiIgnore
注解。
如果想在文档中屏蔽掉删除用户的接口(user/delete),那么只需要在删除用户的方法上加上 @ApiIgnore 即可。
@ApiIgnore public boolean delete(@PathVariable("id") int id)
apis()
和 paths()
两 个方法来帮助我们在不同级别上过滤接口: apis() paths()
在集成 Swagger2 的章节中我们这两个方法指定的都是扫描所有,没有指定任何过滤条件。如果我们在我们修改之前定义的 Docket 对象的 apis()
方法和 paths()
方法为下面的内容,那么接口文档将只会展示 /user/add 和 /user/find/{id} 两个接口。
.apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller")) .paths(Predicates.or(PathSelectors.ant("/user/add"), PathSelectors.ant("/user/find/*")))
Swagger 允许我们通过 Docket 的 globalResponseMessage()
方法全局覆盖 HTTP 方法的响应消息,但是首先我们得通过 Docket 的 useDefaultResponseMessages
方法告诉 Swagger 不使用默认的 HTTP 响应消息,假设我们现在需要覆盖所有 GET 方法的 500 和 403 错误的响应消息,我们只需要在 SwaggerConfig.java 类中的 Docket Bean 下添加如下内容:
.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 错误的响应消息都变成了我们自定义的内容。
SwaggerUI 会以列表的方式展示所有扫描到的接口,初始状态是收缩的,我们只需要点击展开就好,而且会在左边标识接口的请求方式(GET、POST、PUT、DELETE 等等)。
如下图所示,点击接口展开后页面右上角的 Try it out 按钮后,页面会变成如图所示:
SwaggerUI 会给我们自动填充请求参数的数据结构,我们需要做的只是点击 Execute 即可发起调用
如下图所示,SwaggerUI 会通过我们在实体上使用的 @ApiModel
注解以及 @ApiModelProperty
注解来自动补充实体以及其属性的描述和备注。
在本章节中我将给出一些 Swagger 中常用的注解以及其常用的属性,并对其一一解释,方便您查看。
@Api
: 可设置对控制器的描述。
注解属性 | 类型 | 描述 |
---|---|---|
tags | String[] | 控制器标签。 |
description | String | 控制器描述(该字段被申明为过期)。 |
@ApiOperation
: 可设置对接口的描述。 注解属性 | 类型 | 描述 |
---|---|---|
value | String | 接口说明。 |
notes | String | 接口发布说明。 |
tags | Stirng[] | 标签。 |
response | Class<?> | 接口返回类型。 |
httpMethod | String | 接口请求方式。 |
@ApiIgnore
: Swagger 文档不会显示拥有该注解的接口。 @ApiImplicitParams
: 用于描述接口的非对象参数集。 @ApiImplicitParam
: 用于描述接口的非对象参数,一般与 @ApiImplicitParams
组合使用。 注解属性 | 描述 |
---|---|
paramType | 查询参数类型,实际上就是参数放在那里。取值:
|
dataType | 参数的数据类型。取值:
|
name | 参数名字。 |
value | 参数意义的描述。 |
required | 是否必填。取值:
|
@ApiModel
: 可设置接口相关实体的描述。 @ApiModelProperty
: 可设置实体属性的相关描述。 注解属性 | 类型 | 描述 |
---|---|---|
value | String | 字段说明。 |
name | String | 重写字段名称。 |
dataType | Stirng | 重写字段类型。 |
required | boolean | 是否必填。 |
example | Stirng | 举例说明。 |
hidden | boolean | 是否在文档中隐藏该字段。 |
allowEmptyValue | boolean | 是否允许为空。 |
allowableValues | String | 该字段允许的值,当我们 API 的某个参数为枚举类型时,使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。 |
在本教程中,我们学会了如何使用 Swagger 2 来生成 Spring Boot REST API 的文档。我们还研究了如何过滤 API、自定义 HTTP 响应消息以及如何使用 SwaggerUI 直接调用我们的 API。您可以在 Github 上找到本教程的 完整实现 ,这是一个基于 IntelliJ IDEA 的项目,因此它应该很容易导入和运行,当然如果您想对本教程做补充的话欢迎发邮件给我 (gancy.programmer@gmail.com) 或者直接在 GitHub 上提交 Pull Request。