太原做网站找谁,邢台123招聘信息网,河南网站推广怎么做,懒人免费建站模板一、简介
在当下这个前后端分离的技术趋势下#xff0c;前端工程师过度依赖后端工程师的接口和数据#xff0c;给开发带来了两大问题#xff1a; 问题一、后端接口查看难#xff1a;要怎么调用#xff1f;参数怎么传递#xff1f;有几个参数#xff1f;参数都代表什么含…一、简介
在当下这个前后端分离的技术趋势下前端工程师过度依赖后端工程师的接口和数据给开发带来了两大问题 问题一、后端接口查看难要怎么调用参数怎么传递有几个参数参数都代表什么含义问题二、返回数据操作难数据返回不对或者不够怎么办怎么才能灵活的操作数据
这是很多公司前后端分离之后带来的困扰那怎么来解决这些问题
问题一的一般解决方案后端团队共同维护一个在线文档每次改接口再去改对应的文档但难免会遗漏花的大力气但却效果平平。
问题二的一般解决方案自己搭建一个Mock服务器然后一个接口一个接口手动去录规则还是一个费力的体力活。
那有没有最优的解决方案来解决以上两个问题呢答案是肯定的那就是将要登场的“Swagger”和“Easy Mock”。
1.1 Swagger介绍
Swagger是全球最流行的接口文档自动生成和测试的框架几乎支持所有的开发语言。
Swagger官网地址https://swagger.io/
1.2 Easy Mock介绍
Easy Mock是一个可视化并且能快速生成 模拟数据 的持久化服务。
Easy Mock能一键导入Swagger所有接口省去了手动录制接口的麻烦而且能够完美的适配Swagger中的代码注释可谓开发利器。
Easy Mock数据是保存在云端的而且可以创建团队项目可以真正的实现前端脱离后端进行项目开发。
接下来一起来看看怎么在项目中集成Swagger和Easy Mock吧。
1.3 开发环境
JDK 8Spring Boot 2.0.4Swagger 2.9.2IDEA 2018.2
二、Swagger集成
本文介绍的Swagger是基于Spring Boot框架的一起来看具体的实现步骤。
2.1 添加依赖
配置pom.xml添加如下代码
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version
/dependency
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version
/dependency其中
springfox-swagger2 用于JSON API文档的生成springfox-swagger-ui 用于文档界面展示。
更多版本请访问
springfox-swagger2http://mvnrepository.com/artifact/io.springfox/springfox-swagger2
springfox-swagger-uihttp://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
2.2 注册Swagger
在源码的根目录也就是Appliction.java的同级目录创建Java类“SwaggerConfig.java”命名无所谓代码如下
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static springfox.documentation.builders.PathSelectors.regex;Configuration
EnableSwagger2
ConditionalOnExpression(${swagger.enable:true})
public class SwaggerConfig {Beanpublic Docket swaggerSpringMvcPlugin() {ApiInfo apiInfo new ApiInfo(Spring Boot APIs,Spring Boot Swagger2,1.0.0,null,王磊的博客,作者王磊,http://www.apigo.cn/);Docket docket new Docket(DocumentationType.SWAGGER_2).select().paths(regex(/api/.*)).build().apiInfo(apiInfo).useDefaultResponseMessages(false);return docket;}
}其中“ConditionalOnExpression”为Spring的注解用户是否实例化本类用于是否启用Swagger的判断生产环境需要屏蔽Swagger。
2.3 生产环境禁用Swagger
是否启用Swagger是在application.properties文件里配置的配置如下 swagger.enabletrue 生产环境禁用设置为false即可。
2.4 添加文档注释
完成以上三个步骤已经完成了Spring Boot对Swagger的集成但是文档不够友好比如类、接口的中文说明、参数的说明是没有的需要在代码中完成。
如下代码
RestController
RequestMapping(/api/user)
Api(tags 用户控制器)
public class UserController {ApiOperation(value 打招呼, notes 测试方法)ApiImplicitParam(name name, value 姓名)RequestMapping(value /sayhi, method RequestMethod.POST)public String sayHi(String name) {return Hello, name;}ApiOperation(value 获取所有用户, notes 查询分页数据)RequestMapping(value /getall, method RequestMethod.POST)public String getAll() {return 所有用户;}
}写完代码运行项目在浏览器输入http://localhost:8080/swagger-ui.html 查看添加注释的效果如下图 其中Api是用来描述类的ApiOperation是用来描述方法的ApiImplicitParam是用来描述参数的更多注解说明请看下文。
示例源码下载https://github.com/vipstone/springboot-example/tree/master/springboot-swagger
三、Swagger文档注解
我们现在已经对Swagger有了初步的认识本节重点来看Swagger注解的使用。
Swagger注解的作用是给接口添加注释的。
3.1 Api 类注释
Api用来描述类的属性如下
tags 描述类的用途value 对显示而言没有任何用途可以不用设置
代码示例 Api(tags “文章接口”) 3.2 ApiOperation 方法注释
ApiOperation用来描述方法的属性如下
value 方法的描述notes 方法备注说明
代码示例 ApiOperation(value “获取所有文章”, notes “查询分页数据”) 效果如下图 3.3 ApiImplicitParams 参数注释
ApiImplicitParams描述多参数
ApiImplicitParam描述单参数
属性如下
name 参数value 参数的描述required 是否必传paramType 参数存放位置header、query、path(resuful接口)、body、formdataType 参数类型defaultValue 参数默认值
代码示例 ApiImplicitParams({ ApiImplicitParam(name “name”, value “姓名”, required true, paramType “form”), ApiImplicitParam(name “age”, value “年龄”, required true, paramType “form”), }) 效果如下图 3.4 ApiModel 实体对象描述
ApiModel实体类名描述属性如下
description 类描述
ApiModelProperty字段描述属性如下
value 字段描述
示例如下
ApiModel(description 返回响应数据)
public class RestMessage implements Serializable{ApiModelProperty(value 是否成功)private boolean successtrue;ApiModelProperty(value 返回对象)private Object data;ApiModelProperty(value 错误编号)private Integer errCode;ApiModelProperty(value 错误信息)private String message;/* getter/setter */
}四、Easy Mock使用
Easy Mock是在线的Mock模拟服务器注册账号即可使用数据存储云端使用简单不需要在本地进行任何配置具体操作步骤如下文。
4.1 注册账号
浏览器输入https://easy-mock.com/login 注册账号
4.2 配置Easy Mock项目
进入管理页面之后点击演示个人演示项目默认创建的可以直接拿来用如下图 进入接口列表点击设置点击Swagger Docs API选择Upload本地文件上传如下图 4.3 导出Swagger接口
浏览器访问http://localhost:8080/v2/api-docs 就看到项目的所有接口JSON格式的右键另存为文件如下图 继续4.2的操作上传刚刚保存的JSON文件到Easy Mock。
4.4 更新接口
保存完JSON数据之后就返回到项目的设置页了这个时候点击“同步Swagger”就看到所有接口了。如下图 到此为所有的接口已经导入了可以点击接口列表右侧的复制按钮进行愉快的调用了。
这个时候就可以完全脱离后端了点击接口详情可以看出Easy Mock完美识别了Swagger注释也有了如下图 4.5 修改数据
接口的调用没问题接下来就是修改操作数据了点击右侧的相应接口的修改按钮如下图 进入编辑页面你现在编辑的数据就是接口要返回的数据数据是JSON格式的并且是在线保存云端无须担心数据丢失如下图 编辑完直接点击更新接口即可注意编辑页面还有一个预览按钮点入可以模拟请求这下连Postman都省了效果如下 五、总结
到此为止所有内容已经演示完了我们解决前后端分离带来接口管理难、数据操作难的问题。自动生成接口文档、一键模拟数据让我们不再依赖后端只专注前端的业务等后端把接口写完之后再进行联合调试就可以了这样我们就不费吹灰之力搞定了所有难题并且灵活的配置让我们可以不影响和污染生产环境生产环境设置禁用Swagger即可并且有了预览功能之后我们甚至连Postman都省了。
参考资料
swagger2 注解说明https://blog.csdn.net/xiaojin21cen/article/details/78654652
