Swagger(一) Swagger/Springfox 入门简介

转载自：https://blog.csdn.net/donglinjob/article/details/108550636

 Swagger/Springfox 入门简介

一、 Swagger  简介

1 前言

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。

很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。

如果接口文档可以实时动态生成就不会出现上面问题。

Swagger 可以完美的解决上面的问题。

2 Open API  是什么

Open API 规范(OpenAPI Specification)以前叫做 Swagger 规范，是REST API 的 API 描述格式。

Open API 文件允许描述整个 API，包括：

•  每个访问地址的类型。POST 或 GET。
•  每个操作的参数。包括输入输出参数。
•  认证方法。
•  连接信息，声明，使用团队和其他信息。

Open API 规范可以使用 YAML 或 JSON 格式进行编写。这样更利于我们和机器进行阅读。

OpenAPI 规范（OAS）为 RESTful API 定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实
现逻辑来理解远程服务并与之交互。

然后，文档生成工具可以使用 OpenAPI 定义来显示 API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多其他用例。

源码和说明参照：

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasDocument

3 Swagger  简介

Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API。

Swagger 工具包括的组件：

• Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。
• Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。
• Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
• Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
• Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 SwaggerHub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

二、 Springfox

使用 Swagger 时如果碰见版本更新或迭代时，只需要更改Swagger 的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml 或 json）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。

Marty Pitt 编写了一个基于 Spring 的组件 swagger-springmvc。Spring-fox 就是根据这个组件发展而来的全新项目。

Spring-fox 是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。

Spring-fox 利用自身 AOP 特性，把 Swagger 集成进来，底层还是Swagger。但是使用起来确方便很多。

所以在实际开发中，都是直接使用 spring-fox。

附：官网地址

http://springfox.github.io/springfox/

附：官方源码

https://github.com/springfox/springfox

三、 Swagger  极致用法

1 编写 SpringBoot  项目

编写 SpringBoot 项目，项目中 controller 中包含一个 Handler，测试项目，保证程序可以正确运行。

1.   @RestController
2.   @RequestMapping( "/people")
3.   public class DemoController {
4.   @RequestMapping( "/getPeople")
5.   public People getPeople(Long id, String name){
6.   People peo = w new People();
7.   peo.setId(id);
8.   peo.setName(name);
9.   peo.setAddress(" " 海淀" ");
10.   return peo;
11.   }
12.   }

2 导入 Spring-fox  依赖

在项目的pom.xml中导入Spring-fox依赖。目前最新版本为2.9.2，所以导入的依赖也是这个版本。其中 springfox-swagger2 是核心内容的封装。springfox-swagger-ui 是对 swagger-ui 的封装。

1.   <dependency>
2.   <groupId>io.springfox</groupId>
3.   <artifactId>springfox-swagger2</artifactId>
4.   <version>2.9.2</version>
5.   </dependency>
6.   <dependency>
7.   <groupId>io.springfox</groupId>
8.   <artifactId>springfox-swagger-ui</artifactId>
9.   <version>2.9.2</version>
10.   </dependency>

3 添加注解

在 SpringBoot 的启动类中添加@EnableSwagger2 注解。

添加此注解后表示对当前项目中全部控制器进行扫描。应用Swagger2

1.   @SpringBootApplication
2.   @EnableSwagger2
3.   public class MyApp {
4.   public static void main(String [] args){
5.   SpringApplication.run(MyApp.class,args);
6.   }
7.   }

4 访问 swagger-ui

启动项目后在浏览器中输入http://ip:port/swagger-ui.html即可以访问到 swagger-ui 页面，在页面中可以可视化的进行操作项目中所有接口。

四、 Swagger-UI  使用

访问 swagger-ui.html 后可以在页面中看到所有需要生成接口文档的控制器名称。

每个控制器中间包含多所有控制器方法的各种访问方式。如果使用的是@RequestMapping 进行映射，将显示下面的所有请求方式。如果使用@PostMapping 将只有 Post 方式可以能访问，下面也就只显示Post 的一个。

点击某个请求方式中 try it out

会出现界面要求输入的值。输入完成后点击 Execute 按钮

下面会出现 Request URL 已经不同状态码相应回来的结果。