一. 简介
OpenAPI 规范（以前称为 Swagger 规范）是 REST API 的 API 描述格式。
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
作用
API 描述自身结构的能力是 OpenAPI 所有出色之处的根源。编写完成后，OpenAPI 规范和 Swagger 工具可以通过各种方式进一步推动 API 开发：
- 设计优先用户：使用 Swagger Codegen 为您的 API 生成服务器存根。剩下的唯一事情就是实现服务器逻辑 - 您的 API 已经准备好上线了！
- 使用 Swagger Codegen 为您的 API 生成 40 多种语言的客户端库。
- 使用 Swagger UI 生成交互式 API 文档，让用户可以直接在浏览器中试用 API 调用。
- 使用规范将 API 相关工具连接到您的 API。例如，将规范导入 SoapUI 以为您的 API 创建自动化测试。
优势
- 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
- 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
二. 基本使用
1. 导入相关依赖
通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-spring-web</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>2. 开启 Swagger
-
新建一个 SwaggerConfig 类
-
添加 @Configuration:表明这是一个配置类
-
开启 Swagger2
1> 编写配置文件
在配置文件 config 目录下，添加 swagger 的配置文件 SwaggerConfig.java
@Configuration//标记配置类
@EnableSwagger2//开启在线接口文档
public class SwaggerConfig {
}
2> 测试 Swagger2 是否启动成功
这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入：http://localhost:8089/swagger-ui.html 即可查看 swagger 文档。
可以看到 Swagger 文档中大概有这四类信息
- 组
- 基本信息
- 接口信息
- 实体类信息
