研发团队如何写好API接口文档
2018-05-30 23:37
183 查看
研发团队如何写好API接口文档
导读
背景痛点在哪?
为什么要写接口文档?
API规范
接口工具
总结
背景
随着业务的发展,支撑组的项目也是越来越多。同时,从整个支撑组项目架构体系(含运维和运营体系),我们对系统业务水平拆分,垂直分层,让业务系统更加清晰,产生了一系列平台和子系统,并使用接口进行数据交互。伴随着业务的发展,接口营运而生,并且会越来越多。
痛点在哪
我们运营和维护着诸多的对外接口,很多现有的接口服务寄宿在各个不同的项目,哪些应用在使用api也没有管理起来。并且以前的调用模式也是比较复杂,排错困难。
工作中也有合作开发的同事多次强力要求给出api文档,特别是每个开发组都来要一次,往往解释半天,大家也很痛苦。那么,让不开的问题是,如何管理和维护这些api,才能让大家都轻松?
没有接口文档
接口在代码里,只能看代码
没有集中的的api项目
相同业务的api分散在不同的项目
查找困难
代码和文档不匹配
代码接口更新,文档不更新
文档不规范
有的是word,有的是excel,有的是txt等等
api不规范
命名,参数不规范
撸码一分钟,对接三小时
为什么要写接口文档?
项目开发过程中服务端和客户端工程师有一个统一的文件进行沟通交流开发项目维护中或者项目人员更迭,方便后期人员查看、维护
API规范
接口名称这里统一使用小写 如:api/order/get
可参考跟着Github学习Restful HTTP API 设计
uri
提供客户端使用的全路径
如http://172.16.0.194:8057/api/order/get
请求协议
Http,Https
请求方式
POST,GET等
头部(系统参数)
加密签名,时间戳等
请求参数(业务)
业务相关的输入参数
响应参数(业务)
输出参数
返回示例
定义返货结果数据结构,更直观
1.返回成功
2.返回失败
接口工具
eolinker以后都使用该工具作为api归档
![](http://ou71ojlz3.bkt.clouddn.com/%E7%9F%AD%E4%BF%A1api.png)
![](http://ou71ojlz3.bkt.clouddn.com/homeapi.png)
项目中使用restfulapi的情况较多,webservice,wcf,webapi均支持,所以这里该规范重点针对resfulapi。
有了规范更能减少沟通误差,提高工作效率
总结
项目中使用restfulapi的情况较多,webservice,wcf,webapi均支持,所以这里该规范重点针对resfulapi。有了规范更能减少沟通误差,提高工作效率
微信公众号:码农商业参谋
![](http://ou71ojlz3.bkt.clouddn.com/%E7%A0%81%E5%86%9C%E5%95%86%E4%B8%9A%E5%8F%82%E8%B0%8B%20%282%29.jpg)
相关文章推荐
- 研发团队如何写好API接口文档
- 大学如何组织管理外包团队进行研发?
- 技术团队如何维护文档
- 如何写好软件开发需求文档
- 如何组建一个合理的研发团队?
- 程序员,如何写好文档?
- 如何做好架构设计与写好架构设计的文档
- 如何应对研发团队从30人到1000的挑战
- 如何做好架构设计与写好架构设计的文档?
- 如何组建一个合理的研发团队?
- 如何打造139团队(不同层次人员的选择与培养,大型研发团队,大型敏捷开发团队)
- 如何写好一份产品需求文档
- 如何成为一名研发主管--关于个人、过程、工具和团队之一
- 如何提升团队的研发效率?来听听阿里研发专家是怎么说的
- 团队各成员如何使用GitHub共同编辑文档?
- 如何判断一个已经写好的MFC程序是单文档还是多文档?
- [研发管理]如何做好小团队的开发规范?
- 如何构建《健康,成长,快乐,高效》的研发团队
- 如何打造139团队(不同层次人员的选择与培养,大型研发团队,大型敏捷开发团队)
- 研发管理07:Agile Coach---如何构建敏捷项目管理团队---从自身做起