Swagger的介绍与使用（一）

一. 简介

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 文档中大概有这四类信息

• 组
• 基本信息
• 接口信息
• 实体类信息