这是张富涛的第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生成的文档界面很美吧?下面我们看一下每个接口文档点开之后是什么样子的。
我们以登录接口举例,当我们点开登录的接口后,抽屉展开登录接口的详细内容, 从上到下分别为:
- 接口详细介绍
- 返回结果及返回类型
- 接口提交参数、参数说明、参数类型(同时可在此处输入接口测试数据)
- 访问状态值说明
- 测试按钮
以上内容都是我们自己设定的,根据程序逻辑生成的数据
同时在这个页面也可以看到返回值的说明
此时如果我希望测试接口,可以在“提交参数”的输入框内输入数据,点击“Try it out!”,进行单元测试。
Swagger会返回生成的测试连接、请求和返回状态、头部、值。是一个比PostMan更加方便的单元测试工具!
怎么样,Swagger是不是很不错的生成文档工具呢?我们将会在下一篇文章介绍Swagger如何与SpringMVC框架结合,项目中如何导入Swagger,并且如何使用,请大家期待吧!么么哒!
---------------
公众号:张富涛的学习笔记(ID:futaoNT)
知乎:张富涛
CSDN:张富涛
这是一个在夜晚可以靠编程拯救世界的程序员,关注他将在第一时间获悉他的知识、工作心得!
长按下图二维码关注: