如何做好API开发 文档
难,是真的难!
❝
程序员最讨厌的两件事:1. 写文档,2. 别人不写文档。大多数开发人员不愿意写 API 文档的原因:
写文档短期收益远低于付出的成本
,然而并不是所有人都能够坚持做有长期收益
的事情的。你因为写文档而耽误了当前项目进度,老板会直接找你麻烦;但是因为没写文档而带来的长期收益低,老板是看不见的。这就是现实,让人去做违反人性的事情是非常困难的。❞
作为一个前后端分离模式开发的团队,我们经常会看到这样的场景:前端开发和后端开发在一起热烈的讨论“你这接口参数怎么又变了?”,“接口怎么又不通了?”,“稍等,我调试下”,“你再试试..."。
那能不能写好接口文档,大家都按文档来开发?很难,因为写文档、维护文档比较麻烦,而且费时,还会经常出现 API 更新了,但文档还是旧的,各种同步不一致的情况,从而耽搁彼此的时间。
之前我们团队也遇到了同样的问题,那么作为研发团队的负责人,我是如何带领团队解决这个问题的呢?
如何做?
方法其实很简单,如果能做到让写文档/维护文档这件事情的短期收益
就能远高于付出的成本
,那么所有问题都能迎刃而解,开发人员就会非常乐意去写接口文档。
团队原来的工作模式
「API 设计人员」使用 Swagger 写接口文档
「前端开发」 使用 RAP mock 接口数据
「后端开发」 使用 Postman 调试接口
「测试人员」 使用 JMeter 测试接口
我们遇到的问题
我们团队是前后端同步进入开发的,不能等后端开发完了才出接口文档,前端再进入开发,所以使用后端代码注释自动生成 Swagger 不适合我们。
写 Swagger 文档效率很低,并且有学习门槛,让团队所有人都熟练手写 Swagger 文档是不现实的,更何况团队不停有新人进来。
开发人员在 Swagger 定义好文档后,接口调试的时候还需要去 Postman 再定义一遍。
前端开发 Mock 数据的时候又要去 RAP 定义一遍,手动设置好 Mock 规则。
测试人员需要去 JMeter 定义一遍。
前端根据 RAP Mock 出来的数据开发完,后端根据 Swagger 定义的接口文档开发完,各自测试测试通过了,本以为可以马上上线,结果一对接发现各种问题:原来开发过程中接口变更,只修改了 Swagger,但是没有及时同步修改 RAP。
同样,测试在 JMeter 写好的测试用例,真正运行的时候也会发现各种不一致。
开发过程,经常会有发现开始定义的接口文档有不合理的地方,需要临时调整,经常出现接口改了,但是文档没有更新。
时间久了,各种不一致会越来越严重。
如何解决
要做到写文档和及时维护文档的短期收益
就能远高于付出的成本
,无非两个方向:
降低写文档的成本
增加写文档后的收益
鉴于此,我们设想如果有一款工具做到以下这些是不是就非常爽了?
以
完全可视化
的界面来编写文档,并且是零学习成本,「新人」 一来就能上手。可以通过接口文档定义的数据结构
自动 mock
出数据,而无需 「前端开发」 再写mock
规则。「后端开发」 在接口文档基础上调试接口,而无需在去
Postman
上调试;接口如有变化,调试的时候就自动更新了文档,零成本的保障了接口维护的及时性。「后端开发」 每次调试完一个功能就保存为一个
接口用例
。「测试人员」 直接使用
接口用例
测试接口。「测试人员」 更加接口文档自动生成测试用例,然后像
JMeter
一样在直接在上面测试。根据接口文档定义的数据结构,自动生成前后端的
数据模型
代码。
总结下来,我们需要的就是这么一款工具:
❝
通过一套系统、一份数据,解决多个系统之间的数据同步问题。只要定义好接口文档,接口调试、数据 Mock、接口测试就可以直接使用,无需再次定义;接口文档和接口开发调试使用同一个工具,接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确!
❞
为此,我们几乎尝遍了市面上所有相关的工具,但是很遗憾,没有找到合适的。
怎么办?自己干!
于是,我们自己实现了一个Postman + Swagger + RAP + JMeter
这个工具就是 Apifox
,经常很长一段时间不断更新迭代后,我们基本上完全实现了最初的设想,几乎完美解决了最开始遇到的所有问题,在公司内部大受欢迎。并且也形成了我们自己的最佳实践。
最佳实践
「前端」(或「后端」)在 「Apifox」 上定好
接口文档
初稿。「前后端」 一起评审、完善
接口文档
,定好接口用例
。「前端」 使用系统根据接口文档自动生成的
Mock 数据
进入开发。「后端」 使用
接口用例
调试开发中接口,系统根据接口文档的定义自动校验
返回的数据是否正确,只要所有接口用例调试通过,接口就开发完成了。「后端」 开发完成后,「测试人员」(也可以是「后端」)使用
集合测试
功能进行多接口集成测试,完整测试整个接口调用流程。「前后端」 都开发完,前端从
Mock 数据
切换到正式数据
,联调通常都会非常顺利,因为前后端双方都完全遵守了接口定义的规范。
对外服务
没错,现在我们已经将Apifox
产品化对外服务了,你们团队也可以直接使用Apifox
了。
官网:www.apifox.cn
Apifox 解决方案
一、如何解决这些问题
1、Apifox 定位
Apifox = Postman + Swagger + Mock + JMeter
Apifox 是 API 文档、API 调试、API Mock、API 自动化测试一体化协作平台。
通过一套系统、一份数据,解决多个系统之间的数据同步问题。只要定义好接口文档,接口调试、数据 Mock、接口测试就可以直接使用,无需再次定义;接口文档和接口开发调试使用同一个工具,接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确!
2、Apifox 宗旨
节省研发团队的每一分钟!
3、Apifox 功能
「接口设计」:Apifox 接口文档遵循 OpenApi 3.0 (原 Swagger)、JSON Schema 规范的同时,提供了非常好用的
可视化
文档管理功能,零学习成本,非常高效。并且支持在线分享接口文档。「数据模型」:可复用的数据结构,定义接口
返回数据结构
及请求参数数据结构
(仅 JSON 和 XML 模式)时可直接引用。支持模型直接嵌套引用,直接 JSON/XML 智能导入,支持 oneOf、allOf 等高级组合模式。「接口调试」:Postman 有的功能,比如环境变量、前置/后置脚本、Cookie/Session 全局共享 等功能,Apifox 都有,并且比 Postman 更高效好用。接口运行完之后点击
保存为用例
按钮,即可生成接口用例
,后续可直接运行接口用例,无需再输入参数,非常方便。自定义脚本 100% 兼容 Postman 语法,并且支持运行javascript、java、python、php、js、BeanShell、go、shell、ruby、lua等各种语言代码。「接口用例」:通常一个接口会有多种情况用例,比如
参数正确
用例、参数错误
用例、数据为空
用例、不同数据状态
用例等等。运行接口用例时会自动校验数据正确性,用接口用例来调试接口非常高效。「接口数据 Mock」:内置 Mock.js 规则引擎,非常方便 mock 出各种数据,并且可以在定义数据结构的同时写好 mock 规则。支持添加“期望”,根据请求参数返回不同 mock 数据。最重要的是 Apifox
零配置
即可 Mock 出非常人性化的数据,具体在本文后面介绍。「数据库操作」:支持读取数据库数据,作为接口请求参数使用。支持读取数据库数据,用来校验(断言)接口请求是否成功。
「接口自动化测试」:提供接口集合测试,可以通过选择接口(或接口用例)快速创建测试集。目前接口自动化测试更多功能还在开发中,敬请期待!目标是:JMeter 有的功能基本都会有,并且要更好用。
「快捷调试」:类似 Postman 的接口调试方式,主要用途为临时调试一些
无需文档化
的接口,无需提前定义接口即可快速调试。「代码生成」:根据接口及数据数据模型定义,系统自动生成
接口请求代码
、前端业务代码
及后端业务代码
。「团队协作」:Apifox 天生就是为团队协作而生的,接口云端实时同步更新,成熟的
团队/项目/成员权限
管理,满足各类企业的需求。
二、Apifox 做的不仅仅是数据打通
如果你认为 Apifox 只做了数据打通,来提升研发团队的效率,那就错了。Apifox 还做了非常多的创新,来提升开发人员的效率。
1、接口支持“用例管理”
通常一个接口会有多种情况用例,比如 正确用例
参数错误用例
数据为空用例
不同数据状态用例
。定义接口的时候定义好这些不同状态的用例,接口调试的时候直接运行,非常高效。
2、“数据模型”定义、引用
可以独立定义数据模型,接口定义时可以直接引用数据模型,数据模型之间也可以相互引用。同样的数据结构,只需要定义一次即可多处使用;修改的时候只需要修改一处,多处实时更新,避免不一致。
3、调试时“自动校验”数据结构
使用 Apifox 调试接口的时候,系统会根据接口文档里的定义,自动校验返回的数据结构是否正确,无需通过肉眼识别,也无需手动写断言脚本检测,非常高效!
Apifox 自动校验数据结构
4、“可视化”设置断言
设置断言:
Apifox 设置断言
运行后,查看断言结果:
5、“可视化”设置提取变量
6、支持数据库操作
7、“零配置”Mock 出非常人性化的数据
先放一张图对比下 Apifox 和其他同类工具 零配置
mock 出来的数据效果:
Apifox Mock 数据结果对比同类工具
可以看出 Apifox 零配置
Mock 出来的数据和真实情况是非常接近的,前端开发可以直接使用,而无需再手动写 mock 规则。
「Apifox 如何做到高效率
、零配置
生成非常人性化的 mock 数据」
Apifox 根据接口定义里的数据结构、数据类型,自动生成 mock 规则。
Apifox 内置智能 mock 规则库,根据字段名、字段数据类型,智能优化自动生成的 mock 规则。如:名称包含字符串
image
的string
类型字段,自动 mock 出一个图片地址 URL;包含字符串time
的string
类型字段,自动 mock 出一个时间字符串;包含字符串city
的string
类型字段,自动 mock 出一个城市名。Apifox 根据内置规则,可自动识别出图片、头像、用户名、手机号、网址、日期、时间、时间戳、邮箱、省份、城市、地址、IP 等字段,从而 Mock 出非常人性化的数据。
除了内置 mock 规则,用户还可以自定义规则库,满足各种个性化需求。支持使用
正则表达式
、通配符
来匹配字段名自定义 mock 规则。
8、生成在线接口文档
Apifox 项目可“在线分享” API 文档,分享出去的 API 文档可设置为公开或需要密码访问,非常方便与外部团队协作。
体验地址:https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285
9、代码自动生成
根据接口模型定义,自动生成各种语言/框架(如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等)的业务代码(如 Model、Controller、单元测试代码等)和接口请求代码。目前 Apifox 支持 130 种语言及框架的代码自动生成。
更重要的是:你可以通过自定义代码模板
来生成符合自己团队的架构规范的代码,满足各种个性化的需求。
10、导入、导出
支持导出
OpenApi (Swagger)
、Markdown
、Html
等数据格式,因为可以导出OpenApi
格式数据,所以你可以利用 OpenApi (Swagger) 丰富的生态工具完成各种接口相关的事情。支持导入
OpenApi (Swagger)
、Postman
、HAR
、RAML
、RAP2
、YApi
、Eolinker
、NEI
、DOClever
、ApiPost
、Apizza
、ShowDoc
、API Blueprint
、I/O Docs
、WADL
、Google Discovery
等数据格式,方便旧项目迁移。
三、后续功能规划
接口文档公开对外发布。
接口性能测试支持(类似 JMeter)。
支持插件市场,可以自己开发插件。
支持更多接口协议,如
GraphQL
、websocket
等。支持离线使用,项目可选择在线同步(团队协作)还是仅本地存储(单机离线使用)。
四、更多 Apifox 功能截图
接口调试
Apifox 多种主题色可选
五、 Apifox 下载地址
请访问 Apifox 官网下载:apifox.cn
↓↓↓ 点击“阅读原文”访问 Apifox 官网
阅读原文
如何做好API开发 文档相关推荐
- js学习总结----crm客户管理系统之项目开发流程和api接口文档
CRM ->客户管理系统 CMS ->内容发布管理系统 ERP ->企业战略信息管理系统 OA -> 企业办公管理系统 产品 / UI设计:需求分析,产品定位,市场调查...按 ...
- 开发日记-20190328 关键词 利用eolinker一键快速生成API接口文档
今天感觉效率真的很低= =各个层面的,apk发布到现场发现出现了问题,所以一个下午都在忙着解决现场出现的问题,领导一直打电话询问进度,午觉也没有睡所以今天预计的很多计划都处于停滞状态,像昨天规划的今天 ...
- Facebook 游戏开发更新文档 API 参考文档 v6.0
Facebook 游戏开发更新文档 API 参考文档 v6.0 更新日志 1.排行榜 此版本全新推出排行榜 API!提供一套强大的 API, 使得游戏可获取排行榜.查询得分 情况和设置新分数(支持分数 ...
- 智表ZCELL产品V1.4.0开发API接口文档 与 产品功能清单
为了方便大家使用ZCELL,应网友要求,整理编写了相关文档,现与产品一起同步发布,供大家下载使用,使用过程中如有疑问,请与我QQ联系. 智表(ZCELL)V1.4.0版本 功能清单文档下载地址: 功 ...
- api服务器开发语言,【API编写】介绍一个国内强大的API接口文档写作网站showdoc - 最好的编程语言 - 博客园...
这几天要写一个接口API文档,经理给我发过来一个,说要弄一个这样的接口文档,我一看,这可麻烦呀,有大纲有详细,我以为要用div+css去一个页面一个页面做呢,这工作量可不小,网站一搜索,竟然有可以直接 ...
- 整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
- echarts4离线使用文档_适合写API接口文档的管理工具有哪些?
现在越来越流行前后端分离开发,使用ajax交互.所以api接口文档就变的十分有意义了,目前市场有哪些比较优秀的接口文档管理工具呢? 1.MinDoc 网址:https://www.iminho.me/ ...
- RESTful API接口文档规范小坑
希望给你3-5分钟的碎片化学习,可能是坐地铁.等公交,积少成多,水滴石穿,谢谢关注. 前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问 ...
- python生成api文档_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求 实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
最新文章
- 收缩临时库 shrink tempdb
- 史上最全的MySQL高性能优化实战总结!
- python数字处理技巧(2): Numpy、矩阵运算、随机、字符串日期
- MVC 之 Partial View 用法
- 前端学习(3302):类组件父组件和子组件createRef
- 利用 nodejs 解析 m3u8 格式文件,并下 ts 合并为 mp4
- linux latex编译器,在Ubuntu系统中下载安装LaTeX编辑器TeXstudio的方法
- windwos上外网
- 腐烂国度计算机配置要求,腐烂国度一周年求生版配置要求 略有小幅度提升
- Error serializing object. Cause: java.io.NotSerializableException: com.qi
- hexo博客yilia-puls主题使用aplayer音乐插件
- Word 里文字对齐推荐这4种方法
- 《大话物联网(第2版)》赠书活动名单公告
- JAVA:实现RodCutting棒材切割问题算法(附完整源码)
- c#构造函数 例子学习
- caused by: java.lang.outofmemory_hadoop运行java.lang.OutOfMemoryError:java heap space错误。
- Mybatis入门到实战
- 请问汽车CD接线各个的字母代表什么,ACC,ILL,RR,FR,FL,RLANT,B/U,NC,CND,真诚的谢谢了
- Eclipse+webservice简单实例搭建
- 教程:动手用自己电脑搭建一个网站 (nat123 花生壳 动态域名 个人电脑做服务器)...
热门文章
- 【Kaggle】Titanic - Machine Learning from Disaster(二)
- 【Redis】查看redis服务的版本
- linux如何批量操作,linux批量操作命令锦集
- Samba 服务使用的端口和协议
- Jackson官网与官方文档
- lenovo电脑的麦克风没有声音?声音小?甚至有杂音,无法聊天?
- 视频消重入门级,学会这个你基本就能靠搬运维持生活自媒体视频如何消重?批量处理去重消重去水印去logo...
- 对于连接Excel时“外部表不是预期的格式”错误的处理
- 聊聊实时音视频中的技术难点:回声消除+噪声消除
- resetFields方法重置表单