RESTful API接口文档规范小坑
希望给你3-5分钟的碎片化学习,可能是坐地铁、等公交,积少成多,水滴石穿,谢谢关注。
前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问题?这里分享一些不成熟的浅见。
Swagger描述
我们在前后端配合的过程中,使用了大多数人使用的Swagger作为服务描述文档,这样的好处很明显,就是后台编写注释,接口调用界面自动生成字段描述。如下图:
随着前后端磨合,默契程度逐步增加,基本上这种描述文档足够联调了。事物总是多变的,随着新人的加入和接口的增加,业务的复杂化,过了大半年,回头望月,接口已经开始出现坏味道。
新人不知道如何维护,连老人也要梳理回忆半天,接口膨胀导致分类不清晰,很难想象如果这个时候,如果你们需要把部分前端功能进行外包会怎样?前端单看Swagger会不会一脸懵逼?
Wiki文档
于是内部开个了专题会,参照市面上大多数的api描述文档,大家同意写到wiki,虽然这种做法除了增加后端人员的工作量,对提升效率不是那么明显,但是整个接口的描述相对就规范一些。
过了一段时间,有一个前端新人进来,带来了小小的烦恼,由于后端接口变更,文档没有及时更新,前端在联调时候经常一脸懵逼,如果能及时发现还好,否则将错就错,测试没注意,发布后经常犯一些写错别字的低级错误。
更加麻烦的是,项目工期赶,决定对前端部分模块进行外包。于是准备好了UI图和接口描述文档,觉得应该可以安心了。承包方拿到UI和文档的时候,除了简单的增删改查接口大概能猜的懂,其他的接口和UI上如何一一匹配?好吧,这该死的接口文档。
图文描述
于是后台兄弟加班加点在UI上给每个功能一一标注对应的接口名称,如下所示,虽然缓解了前端的困惑,但是前后端分离导致的一些效率损失,始终让人耿耿于怀。也许就像DBA经常说的,任何事物都是有代价,不知道大伙有更好的解决方案赐教?
个人小结
1.对前端组件进行分类
比如树、表格、下拉、radio、复选框、时间……越早分类对后面的管理应该会更加有利,因为不同的新人进来,可能同样的树会重新造一种格式。
2.接口数量要控制好
不能太多导致失控,也不能重复两份接口(不同的开发者完全有这种可能),不同的前端组件比如easyUI和elementUI对格式要求是不一样的,如果前后台用的不是同一套UI框架,接口有可能会出现重复。
3.如何规范
每个公司规范不尽相同,可以参考大厂的规范,比如高德,微信或者百度地图。对新入职的新要培训在前,开发中出现新的问题,最好要有专题会进行讨论协商一致,最后口头的东西务必要文档化,否则都不能算是真正的规范。
后话
随着团队人数、业务扩大,如果没有很好的规范,碰到沟通冲突的情况,规范就显得特别重要。我们团队原本两个前后端配合融洽,相安无事,后面来了两个新的前后端,由于言语冲突,一件简单的小事会因为个性不合而被无限放大。尽快统一风格,规范文档化也许可以避免很多类似的问题。
这里给哪些想要做前后端分离的人一个不错的RESTful API的规范,是阮一峰大神的博客,非常值得收藏,推荐下:RESTful API 最佳实践
RESTful API接口文档规范小坑的更多相关文章
- 整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
- Swagger 生成 PHP API 接口文档
Swagger 生成 PHP API 接口文档 Lumen微服务生成Swagger文档 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文 ...
- “小葵日记”API接口文档
"小葵日记"项目API接口文档 时间:2017/10/31 (1)用户登录[待完成] POST:127.0.0.1/index/user/login data 数据别称 数据名 数 ...
- Swagger解决你手写API接口文档的痛
首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结. 01 痛 苦 不做.不行 之前,前后端分离的系统由前端和后端不同的编写,我们苦逼的后端工程师会把自己已经写完的A ...
- Restful API 接口设计标准及规范
Restful API 接口设计标准以及规范 RESTful概念 理解和评估以网络为基础的应用软件的架构设计,得到一个功能强.性能好.适宜通信的架构.REST指的是一组架构约束条件和原则." ...
- Eolinker API 接口文档神器
Eolinker API 接口文档神器 群里小伙伴推荐的,还没有去研究,先记下来. API文档管理.自动化测试.开发协作利器 正在为数万企业管理超过100万APIs,提高开发效率以及规范开发流程
- 构建标准OpenStack API接口文档
1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch ...
- Api接口文档管理工具,你知道哪些呢?
上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的 ...
- SpringBoot + Swagger2 自动生成API接口文档
spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端 ...
随机推荐
- Dashboard二次开发简明教程
Horizon简介 Horizon是OpenStack的一个子项目,用于提供一个Web前端控制台(称为Dashboard),以此来展示OpenStack的功能.通常情况下,我们都是从Horizon.D ...
- 机器学习类别不平衡处理之欠采样(undersampling)
类别不平衡就是指分类任务中不同类别的训练样例数目差别很大的情况 常用的做法有三种,分别是1.欠采样, 2.过采样, 3.阈值移动 由于这几天做的project的target为正值的概率不到4%,且数据 ...
- java 日期类 小结
import java.text.*; import java.util.*; class Test2 { public static void main(String[] args) { Syste ...
- Ubuntu18.04美化主题(mac主题)
前端时间Ubuntu18.04LTS发布,碰巧之前用的Ubuntu16.04出了一点问题,懒得解决,索性就换了Ubuntu18.04. 成果: 参考博客:https://www.cnblogs.com ...
- java quartz 计算近20次执行时间
/** * * @desc 计算表达式近20次时间 * @auth josnow * @date 2017年5月31日 下午12:16:25 * @param cron * @return */ pu ...
- Mysql存储过程 —— SEQUENCE的实现
http://blog.csdn.net/crazylaa/article/details/5368447 创建sql语句: DROP TABLE IF EXISTS sequence; -- 建se ...
- Spring Framework学习要点摘抄
以下摘自Spring Framework官方文档,版本Spring 4.3. <context:annotation-config/> implicitly registered post ...
- MIP 内容声明
从搜索结果页点出的 MIP 页面,其页面上的任何内容(包括但不限于广告.在线咨询.统计等组件)均视为在原站点上的投放和使用. MIP (Mobile Instant Pages - 移动网页加速器), ...
- My97DatePicker日期控件,开始时间不能大于结束时间,结束时间不能小于开始时间
在只做项目的时候,需要用到一个日期控件,之前用到过my97,感觉挺好的,兼容性很强,配置也比较容易 当开始时间不能大于结束时间和结束时间不能小于开始时间,这个需要一个判定的,要不然不就乱套了 在my9 ...
- headfirst设计模式(7)—命令模式
一.前言 什么是命令模式? 在软件系统中,“行为请求者”与“行为实现者”通常呈现一种“紧耦合”.但在某些场合,比如要对行为进行“记录.撤销/重做.事务”等处理,这种无法抵御变化的紧耦合是不合适的.在这 ...