前言

随着项目架构的演化，前后端分离是不可阻挡的趋势。这种模式的协作在实践的过程中经常会遇到的一个问题就是文档。

在《一位CTO告诉我，项目中至少需要这3类文档》一文我们已经描述了文档的重要性，而接口文档便是其中之一，可以说是必不可少的。

但编写接口文档对开发人员来说是一大难题，而且接口还在不断的变化，还要花费精力去维护接口文档的更新。

既然存在痛点，那么必须会出现解决此痛点的产品，这就是Swagger，目前已经更新到Swagger3版本了。如果你还停留在Swagger2，建议升级到Swagger3，整体UI风格及交互友好了不少。

本篇将围绕Swagger3与SpringBoot的集成和离线文档的生成来进行讲解。

Swagger简介

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

Swagger解决的痛点

传统方式提供文档有以下痛点：

• 接口众多，实现细节复杂，编写文档耗费费力，需要持续维护;
• 接口文档需要随时进行同步;
• 接口返回的结果不明确，得构造返回结构体等;
• 不能直接在线测试接口，通常需要额外的工具，比如PostMan等。

当引入Swagger之后，以上痛点迎刃而解，同时还带来以下优点：

• 及时性 (接口变更后，前后端人员可实时看到最新版本)
• 规范性 (接口具体统一风格，如接口地址，请求方式，参数，响应格式和错误信息等)
• 一致性 (接口信息一致，不会因接口文档版本问题出现分歧)
• 可测性 (可直接基于接口文档进行测试)

Swagger3的改变

Swagger3.0的改动，官方文档总结如下几点：

• 删除了对springfox-swagger2的依赖;
• 删除所有@EnableSwagger2…注解;
• 添加了springfox-boot-starter依赖项;
• 移除了guava等第三方依赖;
• 文档访问地址改为http://ip:port/project/swagger-ui/index.html。

下面就来实战使用一下吧。

SpringBoot集成Swagger3

SpringBoot集成Swagger3与SpringBoot集成其他框架的套路基本一致，通常包括：引入依赖、指定配置文件、创建配置类和使用。

引入依赖

在SpringBoot项目的pom.xml中引入Swagger3依赖：

1. <dependency> 
2.     <groupId>io.springfox</groupId> 
3.     <artifactId>springfox-boot-starter</artifactId> 
4.     <version>3.0.0</version> 
5. </dependency> 

指定配置文件

通常情况下swagger只能在开发环境或测试环境下开启，生产环境下需要进行关闭的。而swagger的开启与关闭可在application.properties中进行配置：

1. # 生产环境需设置为false 
2. springfox.documentation.swagger-ui.enabled=true 

配置类

通过@EnableOpenApi注解启动用Swagger的使用，同时在配置类中对Swagger的通用参数进行配置。

1. @Configuration 
2. @EnableOpenApi 
3. public class Swagger3Config { 
4.  
5.     @Bean 
6.     public Docket createRestApi() { 
7.         //返回文档摘要信息 
8.         return new Docket(DocumentationType.OAS_30) 
9.                 .apiInfo(apiInfo()) 
10.                 .select() 
11.                 .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class)) 
12.                 .paths(PathSelectors.any()) 
13.                 .build() 
14.                 .globalRequestParameters(getGlobalRequestParameters()) 
15.                 .globalResponses(HttpMethod.GET, getGlobalResponseMessage()) 
16.                 .globalResponses(HttpMethod.POST, getGlobalResponseMessage()); 
17.     } 
18.  
19.     /** 
20.      * 生成接口信息，包括标题、联系人等 
21.      */ 
22.     private ApiInfo apiInfo() { 
23.         return new ApiInfoBuilder() 
24.                 .title("Swagger3接口文档") 
25.                 .description("如有疑问，可联系二师兄，微信：zhuan2quan") 
26.                 .contact(new Contact("二师兄", "https://www.choupangxia.com/", "secbro2@gmail.com")) 
27.                 .version("1.0") 
28.                 .build(); 
29.     } 
30.  
31.     /** 
32.      * 封装全局通用参数 
33.      */ 
34.     private List<RequestParameter> getGlobalRequestParameters() { 
35.         List<RequestParameter> parameters = new ArrayList<>(); 
36.         parameters.add(new RequestParameterBuilder() 
37.                 .name("uuid") 
38.                 .description("设备uuid") 
39.                 .required(true) 
40.                 .in(ParameterType.QUERY) 
41.                 .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))) 
42.                 .required(false) 
43.                 .build()); 
44.         return parameters; 
45.     } 
46.  
47.     /** 
48.      * 封装通用响应信息 
49.      */ 
50.     private List<Response> getGlobalResponseMessage() { 
51.         List<Response> responseList = new ArrayList<>(); 
52.         responseList.add(new ResponseBuilder().code("404").description("未找到资源").build()); 
53.         return responseList; 
54.     } 
55. } 

通过以上配置已经完成了Spring Boot与Swagger的集成，下面展示一下如何在业务逻辑中进行使用。