谷歌站群系统,河南建设资格执业网站,做网站的教学视频,手机网站如何制作导语#xff1a; 相信无论是前端还是后端开发#xff0c;都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力#xff0c;经常来不及更新。其实无论是前端调用后端#xff0c;还是后端调用后端…导语 相信无论是前端还是后端开发都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力经常来不及更新。其实无论是前端调用后端还是后端调用后端都期望有一个好的接口文档。但是这个接口文档对于程序员来说就跟注释一样经常会抱怨别人写的代码没有写注释然而自己写起代码起来最讨厌的也是写注释。所以仅仅只通过强制来规范大家是不够的随着时间推移版本迭代接口文档往往很容易就跟不上代码了。 Swagger是什么它能干什么 发现了痛点就要去找解决方案。解决方案用的人多了就成了标准的规范这就是Swagger的由来。通过这套规范你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具就可以做到生成各种格式的接口文档生成多种语言的客户端和服务端的代码以及在线接口调试页面等等。这样如果按照新的开发模式在开发新版本或者迭代版本的时候只需要更新Swagger描述文件就可以自动生成接口文档和客户端服务端代码做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此对于许多开发来说编写这个yml或json格式的描述文件本身也是有一定负担的工作特别是在后面持续迭代开发的时候往往会忽略更新这个描述文件直接更改代码。久而久之这个描述文件也和实际项目渐行渐远基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring迅速将Swagger规范纳入自身的标准建立了Spring-swagger项目后面改成了现在的Springfox。通过在项目中引入Springfox可以扫描相关的代码生成该描述文件进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式在后面需求持续迭代的项目中显得尤为重要和高效。
框架说明及使用
1.说明
现在SWAGGER官网主要提供了几种开源工具提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。 Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包dockernode等方式在本地化执行生成。也可以在后面的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中配置Springfoxswagger。这些都能从网上找到而且配置起来都非常的简单。
这里想讲的是如何结合现有的工具和功能设计一个流程去保证一个项目从开始开发到后面持续迭代的时候以最小代价去维护代码、接口文档以及Swagger描述文件。
2.1 项目开始阶段
一般来说接口文档都是由服务端来编写的。在项目开发阶段的时候服务端开发可以视情况来决定是直接编写服务端调用层代码还是写Swagger描述文件。建议是如果项目启动阶段就已经搭好了后台框架那可以直接编写服务端被调用层的代码即controller及其入参出参对象然后通过Springfoxswagger 生成swagger json描述文件。如果项目启动阶段并没有相关后台框架而前端对接口文档追得紧那就建议先编写swagger描述文件通过该描述文件生成接口文档。后续后台框架搭好了也可以生成相关的服务端代码。
2.1 项目迭代阶段
到这个阶段事情就简单很多了。后续后台人员无需关注Swagger描述文件和接口文档有需求变更导致接口变化直接写代码就好了。把调用层的代码做个修改然后生成新的描述文件和接口文档后给到前端即可。真正做到了一劳永逸。
2.3流程
总结一下就是通过下面这两种流程中的一种可以做到代码和接口文档的一致性服务端开发再也不用花费精力去维护接口文档。
流程一 流程二 给Mock系统的正常请求及响应全流程数据
很多时候如果你能在提供接口文档的同时把所有接口的模拟请求响应数据也提供给前端。或者有Mock系统直接将这些模拟数据录入到Mock系统中那将会提高前端的开发效率减少许多发生在联调时候才会发生的问题。
通过适当地在代码中加入swagger的注解可以让你的接口文档描述信息更加详细如果你把每个出入参数的示例值都配上那前端就可以直接在接口文档中拿到模拟数据。相关的注解类及参数配置可以参考文末他人写的技术文章这里也不作展开了。
相关示例注解代码和效果图如下
#####Controller代码
OverrideApiOperation(value post请求调用示例, notes invokePost说明, httpMethod POST)public FFResponseModelDemoOutputDto invokePost(ApiParam(name传入对象,value传入json格式,requiredtrue) RequestBody Valid DemoDto input) {log.info(/testPost is called. input input.toString());return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);}#####接口请求入参对象
Data
ApiModel(value演示类,description请求参数类 )
public class DemoDto implements Serializable {private static final long serialVersionUID 1L;NotNullApiModelProperty(value defaultStr,examplemockStrValue)private String strDemo;NotNullApiModelProperty(example1234343523,required true)private Long longNum;NotNullApiModelProperty(example111111.111)private Double doubleNum;NotNullApiModelProperty(example2018-12-04T13:46:56.711Z)private Date date;}#####接口请求出参公共类
ApiModel(value基础返回类,description基础返回类)
public class FFResponseModelT implements Serializable {private static final long serialVersionUID -2215304260629038881L;// 状态码ApiModelProperty(example成功)private String code;// 业务提示语ApiModelProperty(example000000)private String msg;// 数据对象private T data;...
}#####接口请求出参实际数据对象
Data
public class DemoOutputDto {private String res;NotNullApiModelProperty(value defaultOutputStr,examplemockOutputStrValue)private String outputStrDemo;NotNullApiModelProperty(example6666666,required true)private Long outputLongNum;NotNullApiModelProperty(example88888.888)private Double outputDoubleNum;NotNullApiModelProperty(example2018-12-12T11:11:11.111Z)private Date outputDate;}
效果图
模拟请求数据报文 模拟返回数据报文 总结
其实归根到底使用Swagger就是把相关的信息存储在它定义的描述文件里面yml或json格式再通过维护这个描述文件可以去更新接口文档以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件连描述文件都不需要再去维护了。所有的信息都在代码里面了。代码即接口文档接口文档即代码。
