您的位置:首页 > 运维架构 > 网站架构

研发团队如何写好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归档





项目中使用restfulapi的情况较多,webservice,wcf,webapi均支持,所以这里该规范重点针对resfulapi。

有了规范更能减少沟通误差,提高工作效率

总结

项目中使用restfulapi的情况较多,webservice,wcf,webapi均支持,所以这里该规范重点针对resfulapi。

有了规范更能减少沟通误差,提高工作效率

微信公众号:码农商业参谋

内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息
标签:  架构 API