Swagger 接口文档规范
导语:
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。
Swagger是什么?它能干什么?

发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。
框架说明及使用
1.说明
现在SWAGGER官网主要提供了几种开源工具,提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档,同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包,docker,node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器,该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector: 感觉和postman差不多,是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求,会返回更多的信息,也会保存你请求的实际请求参数等数据。
Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。
PS:
Springfox Swagger: Spring 基于swagger规范,可以将基于SpringMVC和Spring Boot项目的项目代码,自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的,在这里列出来做个说明,方便后面作一个使用的展开。
2.基于Spring框架的Swagger流程应用
这里不会介绍Swagger的工具具体如何使用,不会讲yml或者json格式描述文件的语法规范,也不会讲如何在SpringMVC或者Spring Boot中配置Springfox-swagger。这些都能从网上找到,而且配置起来都非常的简单。
这里想讲的是如何结合现有的工具和功能,设计一个流程,去保证一个项目从开始开发到后面持续迭代的时候,以最小代价去维护代码、接口文档以及Swagger描述文件。
2.1 项目开始阶段
一般来说,接口文档都是由服务端来编写的。在项目开发阶段的时候,服务端开发可以视情况来决定是直接编写服务端调用层代码,还是写Swagger描述文件。建议是如果项目启动阶段,就已经搭好了后台框架,那可以直接编写服务端被调用层的代码(即controller及其入参出参对象),然后通过Springfox-swagger 生成swagger json描述文件。如果项目启动阶段并没有相关后台框架,而前端对接口文档追得紧,那就建议先编写swagger描述文件,通过该描述文件生成接口文档。后续后台框架搭好了,也可以生成相关的服务端代码。
2.1 项目迭代阶段
到这个阶段,事情就简单很多了。后续后台人员,无需关注Swagger描述文件和接口文档,有需求变更导致接口变化,直接写代码就好了。把调用层的代码做个修改,然后生成新的描述文件和接口文档后,给到前端即可。真正做到了一劳永逸。
作者:wuqke
链接:https://www.jianshu.com/p/349e130e40d5
来源:简书
著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。
Swagger 接口文档规范的更多相关文章
- springboot+swagger接口文档企业实践(下)
目录 1.引言 2. swagger接口过滤 2.1 按包过滤(package) 2.2 按类注解过滤 2.3 按方法注解过滤 2.4 按分组过滤 2.4.1 定义注解ApiVersion 2.4.2 ...
- .netcore 3.1高性能微服务架构:加入swagger接口文档
本文为原创文章:首发:http://www.zyiz.net/tech/detail-108663.html swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视 ...
- SpringBoot开发mockserver及生成swagger接口文档
通过springboot开发mock server,包含get及post接口,用于练习接口自动化及jmeter很方便 当然,也为后面jenkins持续集成做基础(开发push代码后 → jenkin ...
- .net core的Swagger接口文档使用教程(二):NSwag
上一篇介绍了Swashbuckle ,地址:.net core的Swagger接口文档使用教程(一):Swashbuckle 讲的东西还挺多,怎奈微软还推荐了一个NSwag,那就继续写吧! 但是和Sw ...
- RESTful API接口文档规范小坑
希望给你3-5分钟的碎片化学习,可能是坐地铁.等公交,积少成多,水滴石穿,谢谢关注. 前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问 ...
- .Net Core---- WebApi生成Swagger接口文档
1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...
- REST-framework快速构建API--生成Swagger接口文档
一.Swagger概述 1.引言 当接口开发完成,紧接着需要编写接口文档.传统的接口文档使用Word编写,or一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次接口有变更,需要手动修改 ...
- springboot+swagger接口文档企业实践(上)
目录 1.引言 2.swagger简介 2.1 swagger 介绍 2.2 springfox.swagger与springboot 3. 使用springboot+swagger构建接口文档 3. ...
- .net core的Swagger接口文档使用教程(一):Swashbuckle
现在的开发大部分都是前后端分离的模式了,后端提供接口,前端调用接口.后端提供了接口,需要对接口进行测试,之前都是使用浏览器开发者工具,或者写单元测试,再或者直接使用Postman,但是现在这些都已经o ...
随机推荐
- getField和getDeclaredField的区别
这两个方法都是用于获取字段getField 只能获取public的,包括从父类继承来的字段.getDeclaredField 可以获取本类所有的字段,包括private的,但是不能获取继承来的字段. ...
- Game and Application Protocol
This privacy policy details the information collected by the team ("we" or "our" ...
- online学习和offline学习
参考:https://blog.csdn.net/a133521741/article/details/79221015 解释: (1)offline学习:每次训练完一个batch后再更新参数: (2 ...
- 【超分辨率】—图像超分辨率(Super-Resolution)技术研究
一.相关概念 1.分辨率 图像分辨率指图像中存储的信息量,是每英寸图像内有多少个像素点,分辨率的单位为PPI(Pixels Per Inch),通常叫做像素每英寸.一般情况下,图像分辨率越高,图像中包 ...
- JS获当前网页元素高度offsetHeight
本文测试的是offsetHeight,获取网页中某元素的高度,单位是像素,获取的类型是整型,可以进行数字运算.如图,网页中的元素本身的高度包括,自身的内容+padding+border,而margin ...
- 数据恢复方法--linux ubuntu--ddrescue
live cd:可以让Linux系统从光盘启动,用户可以方便的先对系统进行一次体验,觉得好用,再进行硬盘安装.ubuntu live cd版:就是可以直接光盘启动的ubuntu系统.Mr. Hou先让 ...
- (模板)AC自动机模板
模板1. 给出模式串和文本串,文本串长度小于1e6,模式串长度之和小于1e6,求文本串中有多少模式串出现. 题目链接:https://www.luogu.org/problem/P3808 AC co ...
- MongoDB 空间定位(点) 与 距离检索
转自: http://blog.csdn.net/flamingsky007/article/details/39208837 基于 MongoDB 2.6 GeoJSON 格式 { "ty ...
- NetworkX一个图论与复杂网络建模工具
NetworkX是一个图论与复杂网络建模工具,采用Python语言开发,内置了常用的图与复杂网络分析算法,可以方便的进行复杂网络数据分析.仿真建模等工作.(1)NetworkX支持创建简单无向图.有向 ...
- Javascript 闭包何时回收?
定义 闭包是函数和声明该函数的词法环境的组合.闭包是指有权访问另一个函数作用域中的变量的函数,创建闭包的最常见的方式就是在一个函数内创建另一个函数,通过另一个函数访问这个函数的局部变量. 范例 fun ...