API文档化开发实战

释放双眼,带上耳机,听听看~!
1序幕:痛苦的来源情景私有化部署需要调试客户部署的机器的时候,部署的环境并不会部署调试工具,当你做好最后无奈只能一边查curl文档一边敲命令的心理准备的时候,你发现curl命令还没有装。然而客户的内网机器不允许外网……2续章:解脱之法这些问题说到底只是http协议本身,前、端后开发人员三者

1 序幕: 痛苦的来源


情景

私有化部署需要调试客户部署的机器的时候,部署的环境并不会部署调试工具, 当你做好最后无奈只能一边查curl文档一边敲命令的心理准备的时候,你发现curl命令还没有装。然而客户的内网机器不允许外网……




2 续章: 解脱之法


这些问题说到底只是http协议本身,前、端后开发人员三者之间确实存在巨大的鸿沟,导致沟通成本巨大。这里就需要我好好地来润滑一下了。我采取的方法是:约定好最常使用的一个公司范围内最小语义子集充当润滑剂,,即API文档化。


2.1 API文档,前后端并行开发

需求进来之后,前后端双方沟通之后约定接口,并提供api文档化,api文档单独进行版本管理,与之产品的设计原型版本大致同步(不一致的情况只有必须调整接口的技术重构),然后前后端并行开发。


2.2 调试

如果说api文档来驱动开发很理想化,那么根据api文档生成同一份请求和返回的mock server则为这种开发流程牢牢的扎稳了脚跟,这里我们实现的mock server不仅仅是常见的接个请求然后返回一个写死http报文, 而是说同样能够识别我们的文档, 生成对应格式的请求和返回http报文, 是否随机、还是指定特定的值,用来做错误或者正确的功能测试都没有任何问题, 到此不仅是前后端的人了解了api, 前后端的代码也真正的识别了api ,在抛开了前后端工程师思想上沟壑之后,当我们的注意力都能聚焦在真正的bug上的时候,我都不敢想象这幅美景,太美了~(事实上回想, 不需要前后端共同开发联调靠喊,确实省了很多心)。


2.3 售后

部署的环境并没有趁手的工具的问题,加之如果是远程连接的话,一般都会很慢,这种情况下调试无疑是低效且痛苦的。为了解决在原始环境下调试的问题,我们将swagger-ui的静态页面跟随产品发布,并且各个部件提供了与之兼容的API的文档,能够在网页上读取API文档直接调试API。

我们现在考虑将swagger-ui的界面提供给售后、实施的同事,甚至客户来操作,抛开命令行,通过页面配置参数的方式来调试api接口发现问题,就不需要每次叫研发来确定发现问题了,而是直接通过售后的具体的api访问的返回来直接确定问题,然后解决了。



3 终章: 动手


谈完了YY的理想,我们来看看怎么将这些东西一步步落地到现实。

API标准: https://github.com/OAI/OpenAPI-Specification ,因为业务场景没有特定到有成熟的restful api的标准,所以我们选择了尽量通用且工具齐备的OpenAPI。


3.1 从代码中提取api文档,提供整套后端的api文档给swagger-ui的页面。

  • Java: jetty有一个现成的插件,能够很方便的从代码中生成api的文档。

  • Python:因为Python的动态语言属性,不能直接效仿java的玩法,所以我给tornado做了一层类似django的中间件的内部python库出来, 在application实例上挂上两个api接口, 来提供api版本、和完整的api文档。

api版本接口是用来检查前后端之间是否说的是同一版本的api,尽量在越早的时间点发现错误。python提供api文档的方式是通过解析注册到application实例上所有路由对应的视图函数(或者说请求处理函数)中的_doc_来实现的,动态生成的方式免去了修改之后多余的生成步骤。


3.2 识别api文档的mock server

这里是前端自己用nodejs撸了一个识别OpenAPI的mock server, 将OpenAPI文档转换到http报文做了这么一层转换, 并在api的版本管理基础上,将各个版本的api文档做了可视化的展示,方便的生成对应的请求、返回http报文来测试功能、错误返回的检查,调试结束之后,改一下api所在的ip地址就可以无缝迁移成生产状态. so easy~


3.3 swagger-ui的定制

  • token的验证; 兼容原始的登陆cookies方式, 如果在非登陆的浏览器里面访问,需要先从login接口拿到token,或者登陆获取cookies, 因为就算是客户内网,各个部件之间的访问安全也是我们关心的, 下一步就是说跟客户的认证系统挂钩,而不是走自己单独的一套认证。

  • 编辑header, http报文; 用swagger-ui的静态页面就是为了能够省去操作命令行、依赖命令行命令的弊端,但是原生的swagger-ui并不支持修改请求的http报文,为此我们做了一些定制化的开发。

  • 一些易用性的定制化, 比如: 支持多个同名查询参数.


到此, 我们就搭建了一个由api文档串联起来的整个开发、测试、售后的完整流程。

给TA买糖
共{{data.count}}人
人已赞赏
HackerNews

CVE-2016-10190 FFmpeg Http协议 heap buffer overflow漏洞分析及利用

2017-9-14 2:59:20

HackerNews

【烧脑题】签到送红包,解题刷礼物,恶斗出题人!

2017-9-14 6:53:01

0 条回复 A文章作者 M管理员
    暂无讨论,说说你的看法吧
个人中心
购物车
优惠劵
今日签到
有新私信 私信列表
搜索