DevOps体系之Swagger

OpenAPI

OpenAPI规范

OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：

有关该API的一般性描述
可用路径（/资源）
在每个路径上的可用操作（获取/提交…）
每个操作的输入/输出格式

目前V2.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。

为啥要使用OpenAPI规范？

OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出
根据OpenAPI规范编写的二进制文本文件，能够像代码一样用任何VCS工具管理起来
一旦编写完成，API文档可以作为：
- 需求和系统特性描述的根据
- 前后台查询、讨论、自测的基础
- 部分或者全部代码自动生成的根据
- 其他重要的作用，比如开放平台开发者的手册…

OpenAPI指开放的应用编程接口，将自己服务的数据通过API提供出去给互联网上其他应用使用。这样做的好处是打破信息孤岛，提高信息的整合效率。

团队协作时的无奈

现代化的研发组织架构中，一个研发团队基本包括了产品组、后端组、前端组、APP端研发、测试组、UI组等，一起协作完成产品的全周期工作。

各项目组进行实质编程协作，构建一份合理高效的接口文档非常重要。

提供接口文档的痛点

横贯各端研发人员，接口众多，细节不一，不容易理解，容易引起‘内战’
在线接口文档，是接口提供方手动导入的，是静态文档
保持实时准确是一个大难题
没有提供接口测试功能
维护的难度不小

Swagger的出现可以完美解决以上痛点。

Swagger

介绍

Swagger（丝袜哥）给人第一印象就是【最（hen）流（niu）行（bai）】，不懂Swagger咱就out了。它的官方网站是http://swagger.io/。

Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

Swagger理念

设计阶段

面向API编程，服务提供方和服务调用方共同遵守契约精神。相当于设计阶段的详细设计文档，对每个接口的输入输出都进行了详细的规定，双方按照API进行开发协作。
开发阶段

站在后端开发的角度，另外再费力经历编写维护一个接口文档，耗时耗力还不讨好。

Swagger核心特性

Swagger提供的一套规范和工具，简化API的文档维护，助力API开发测试。

提供一套API规范 — OpenAPI规范

OpenAPI来自Swagger规范
提供一套工具

Swagger编辑器，基于浏览器的编辑器，您可以在其中编写OpenAPI规范

Swagger UI，将OpenAPI规范呈现为交互式API文档

Swagger Codegen，根据OpenAPI规范生成服务器存根和客户端库

Swagger使用

在Spring项目中使用Swagger

添加Maven依赖项

    <properties><swagger.version>2.9.2</swagger.version></properties><!-- swagger2-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${swagger.version}</version>
</dependency><!-- swagger2-UI-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>${swagger.version}</version>
</dependency>

继承Swagger2到项目中

/*** Swagger2的接口配置* * @author hsax*/
@Configuration
@EnableSwagger2
public class SwaggerConfig
{/*** 创建API*/@Beanpublic Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2)// 是否启用Swagger.enable(true)// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）.apiInfo(apiInfo())// 设置哪些接口暴露给Swagger展示.select()// 扫描所有有注解的api，用这种方式更灵活.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 扫描指定包中的swagger注解// .apis(RequestHandlerSelectors.basePackage("com.hsax.project.tool.swagger"))// 扫描所有 .apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build()}
}

SpringMVC项目中使用Swagger

What？Spirng boot项目？那非SB项目怎么办？

如果没有Spring Boot，您就无法自动配置资源处理程序。Swagger UI添加了一组资源，您必须将这些资源配置为扩展WebMvcConfigurerAdapter的类的一部分，并使用@EnableWebMvc进行批注。

@EnableWebMvc
public class SwaggerConfig extends  WebMvcConfigurerAdapter{public void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

Swagger常用注解

注解	属性	值	备注
@Api	value	字符串	可用在class，class的描述
@ApiOperation	value	字符串	用在方法上
@ApiImplicitParams	[]	ApiImplicitParam数组	参数的描述容器
@ApiImplicitParam	name	字符串	参数
	value	字符串	参数中文描述
	required	布尔值	true/false 是否必须
	dataType	字符串	参数类型
	paramType	字符串	参数请求方式：query/path query:对应@RequestParam?传递；path：对应@PathVariable
@ApiResponses	ApiResponse[]	ApiResponse[]
@ApiResponse	code	整型	返回的状态码
	message	字符串	描述；@ApiResponse(code = 200, message = “Successful”)

Swagger高级特性

过滤Swagger响应的API

并不总是希望公开整个API的文档。可以通过将参数传递给Docket类的apis（）和paths（）方法来限制Swagger的响应。

如上所示，RequestHandlerSelectors允许使用any或none谓词，但也可以用于根据基础包，类注释和方法注释过滤API。

PathSelectors使用谓词提供额外的过滤，这些谓词扫描应用程序的请求路径。您可以使用 any（），none（），regex（）或 ant（）。

在下面的示例中，我们将使用*ant（）*谓词指示Swagger仅包含特定包中的控制器和特定路径。

@Bean
public Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("org.baeldung.web.controller")).paths(PathSelectors.ant("/foos/*")).build();
}

Swagger自定义信息

Swagger还在其响应中提供了一些您可以自定义的默认值，例如“Api文档” ， “由联系人电子邮件创建”，“Apache 2.0”。

要更改这些值，可以使用apiInfo（ApiInfo apiInfo）方法。该ApiInfo类，它包含有关API的自定义信息。

/*** 添加摘要信息*/
private ApiInfo apiInfo()
{// 用ApiInfoBuilder进行定制return new ApiInfoBuilder()// 设置标题.title("标题：华数安信开发平台_接口文档")// 描述.description("描述：用于前端和后端同事调试api使用")// 作者信息.contact(new Contact(ruoyiConfig.getName(), null, null))// 版本.version("版本号:" + ruoyiConfig.getVersion()).build();
}

自定义方法响应

Swagger允许通过Docket的globalResponseMessage（）方法全局覆盖HTTP方法的响应消息。首先，您必须指示Swagger不要使用默认响应消息。

假设您希望覆盖所有GET方法的500和403响应消息。为此，必须将一些代码添加到Docket的初始化块中,（为清楚起见，排除了原始代码）：

.useDefaultResponseMessages(false).globalResponseMessage(RequestMethod.GET,newArrayList(new ResponseMessageBuilder().code(500).message("500 message").responseModel(new ModelRef("Error")).build(),new ResponseMessageBuilder().code(403).message("Forbidden!").build()));

生产环境禁用

可以通过profile注解来处理；三个环境dev， test， prod，我们只在dev环境中使用swagger，test和prod都禁止使用

@Profile(“dev” , ”test”)

如果是mvn package -P dev，这样生成的jar包，启动后可以看到swagger可以正常访问

启动判断写到配置文件中,根据条件判断是否加载，.enable(swaggerShow)
手动配置方式：.paths(PathSelectors.none())//如果是线上环境，添加路径过滤，设置为全部都不符合
Spring boot中有个注解@ConditionalOnProperty，这个注解能够控制某个configuration是否生效；具体操作是通过其两个属性name以及havingValue来实现的，其中name用来从application.properties中读取某个属性值，如果该值为空，则返回false;如果值不为空，则将该值与havingValue指定的值进行比较，如果一样则返回true;否则返回false。如果返回值为false，则该configuration不生效；为true则生效。

Apifox

介绍

Apifox 是集 API 文档、API 调试、API Mock、API 自动化测试多项实用功能为一体的 API 管理平台，定位为 Postman + Swagger + Mock + JMeter。旨在通过一套系统、一份数据，解决多个工具之间的数据同步问题。只需在 Apifox 中定义 API 文档，那么 API 调试、API 数据 Mock、API 自动化测试等功能就可以直接使用，无需再次定义。API 文档和 API 开发调试流程在同一个工具内闭环，API 调试完成后即可确保与 API 文档定义完全一致。高效、及时、准确！

接口管理痛点

大多数研发团队通常会使用以下多种工具管理 API 接口：

使用 Swagger 管理 API 文档
使用 Postman 调试 API
使用 mockjs 等工具 Mock API 数据
使用 JMeter 做 API 自动化测试

维护不同工具之间数据一致性非常困难、低效。并且这里不仅仅是工作量的问题，更大的问题是多个系统之间数据不一致，导致协作低效、频繁出问题，开发与测试人员痛苦不堪。许多研发团队正在经历以下庞杂的协作场景：

架构师在 Swagger 定义好 API 文档后，调试接口时还需要再去 Postman 定义一遍。
前端工程师在开发 Mock 数据时需要在 mockjs 进行定义，还需要手动设置 Mock 规则。
前端工程师根据 mockjs Mock 返回的数据完成开发，后端工程师根据 Swagger 定义的接口文档进行开发，并且各自都通过了测试流程。结果在进入前后端对接流程时又发现各项不一致问题：
1. 开发过程中接口变更了，只修改了 Swagger，但是没有及时同步修改 mockjs。
2. 后端开发的接口数据类型和文档不一致，肉眼难以发现问题。
测试工程师在 JMeter 写好的测试用例，真正运行的时候发现接口有更新，导致需要重复回到 JMeter 重新定义接口参数。

随着开发周期的推移，因为团队中存在过于复杂的工具链路，使得每个环节中的不一致性趋于混乱；开发人员的心智负担越来越重，最终变成了整个团队积重难返的技术债务。而 Apifox 能够有效的解决上述问题。

产品优势

一站式接口协作平台

Apifox = Postman + Swagger + Mock + JMeter

Apifox 是 API 文档、API 调试、API Mock、API 自动化测试一体化协作平台。

接口设计所见即所得

Apifox 接口文档遵循 OpenAPI 3.0 (原 Swagger)、JSON Schema 规范的同时，提供了非常好用的可视化文档管理功能，零学习成本，非常高效。并且支持在线分享接口文档。同一个接口通常会有多种情况，比如 正确用例 参数错误用例 数据为空用例 不同数据状态用例。设计接口时支持定义各个接口的状态。

一次请求，重复调用

无需提前定义接口即可快速调试。支持设置环境变量、前置/后置脚本、Cookie/Session 全局共享等功能。接口运行调试完成后支持一键保存，后续无需输入参数即可重复运行接口用例，十分便利。

自动生成代码

智能化接口管理

使用 Apifox 调试接口的时候，系统会根据接口文档里的定义，自动校验返回的数据结构是否正确。不再需要通过肉眼识别，也无需手动写断言脚本检测。运行接口用例时会自动校验数据正确性，提升调试效率。根据接口及数据数据模型定义，系统还能够自动生成接口请求代码、前端业务代码及后端业务代码。

DevOps体系之Swagger