Swagger简介：前后端分离生成接口文档的工具

Posted 2021-04-30 万方技术

概述

现在的Web开发，越来越多需要做到前后端分离，不但是因为“确认职责”和“提高开发效率”，还要为了移动端提供接口（甚至有些服务器端开发没有Web页面，只为了给移动端提供接口）。

可是做到前后端分离时最大的问题就是沟通成本的问题：没有人专门撰写接口文档、接口文档不能实时更新让前端（包括移动端）开发工程师查看……随着开发技术和设计理念的日新月异，应运而生的“Swagger”出现了。

Swagger号称“世界最流行的API框架”，专业解决“在前后台分离的开发模式中，减小接口定义沟通成本，方便开发过程中测试，自动生成接口文档。”

Swagger完美结合“RESTful API”，针对不同的请求动作单独测试。

Swagger完美结合Java的Spring MVC框架，大大方便了Java开发时实时生成接口文档，这种生成文档的时机为“每次部署时同步生成接口文档，文档目录在项目目录下”

值得一提的是，目前网络上很少相关Swagger整合Spring MVC的文档，即使有也不是特别详细和全面，或多或少有所遗漏，在这里我将尽我所能叙述Swagger的相关知识。

Swagger体验截图

每一个接口可以点开，并查看里面的不同请求动作（如Get、Post等），并有一句简单的提示告知接口功能，这些不同的请求动作建议以RESTful API机制设定接口（如Get获取对象、Post创建对象等……）。具体如下图所示：

怎么样？Swagger生成的文档界面很美吧？下面我们看一下每个接口文档点开之后是什么样子的。

我们以登录接口举例，当我们点开登录的接口后，抽屉展开登录接口的详细内容，从上到下分别为：

1. 接口详细介绍

2. 返回结果及返回类型

3. 接口提交参数、参数说明、参数类型（同时可在此处输入接口测试数据）

4. 访问状态值说明
   

5. 测试按钮

以上内容都是我们自己设定的，根据程序逻辑生成的数据

同时在这个页面也可以看到返回值的说明

此时如果我希望测试接口，可以在“提交参数”的输入框内输入数据，点击“Try it out！”，进行单元测试。

Swagger会返回生成的测试连接、请求和返回状态、头部、值。是一个比PostMan更加方便的单元测试工具！

怎么样，Swagger是不是很不错的生成文档工具呢？我们将会在下一篇文章介绍Swagger如何与SpringMVC框架结合，项目中如何导入Swagger，并且如何使用，请大家期待吧！么么哒！