Spring Boot使用Swagger文档

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增加如下内容即可：

<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的代码，其余代码可以查看源码。

@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所需要的依赖包：

<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类，并增加如下内容:

@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中添加如下内容即可：

<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注解来展开对接口的描述，当然这个注解还可以指定很多内容，我们在下面的相关注解说明章节中详细解释。

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

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

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户id")
private int id;
}

4.文档信息配置，Swagger还支持设置一些文档的版本号、联系人邮箱、网站、版权、开源协议等等信息，但与上面几条不同的是这些信息不是通过注解配置，而是通过创建一个ApiInfo对象，并且使用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());
}

经过上面的步骤，我们的文档将会变成下图的样子，现在看起来就清楚很多了。
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下添加如下内容：

.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

注解属性	类型	描述
tags	String[]	控制器标签。
description	String	控制器描述（该字段被申明为过期）。

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

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

注解属性	类型	描述
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。当然如果你觉得本篇文章还不错的话，顺手给个start，这是对我最好的鼓励。

转自：https://itweknow.cn/blog-site/posts/2111459879.html

posted @ 2019-12-30 16:38 panchanggui 阅读(562) 评论(0) 编辑收藏举报

刷新页面返回顶部

panchanggui