研发团队如何写好API接口文档

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

有了规范更能减小沟通偏差,提升工做效率

---

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