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

这是张富涛的第13篇原创

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

1. 概述

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

swagger官方网站：https://swagger.io/

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

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

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

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

2. Swagger体验截图

进入Swagger自动生成的API文档主页之后，会列出项目提供给前端的所有接口。如Demo示例中有：“上传Token”、“用户信息修改”、“用户注册登录”、“Address收货地址操作”等……

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

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

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

1. 接口详细介绍
2. 返回结果及返回类型
3. 接口提交参数、参数说明、参数类型（同时可在此处输入接口测试数据）
4. 访问状态值说明
5. 测试按钮
   以上内容都是我们自己设定的，根据程序逻辑生成的数据

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

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

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

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

---------------

公众号：张富涛的学习笔记(ID:futaoNT)

知乎：张富涛

CSDN：张富涛

这是一个在夜晚可以靠编程拯救世界的程序员，关注他将在第一时间获悉他的知识、工作心得！

长按下图二维码关注：