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

• 目前已经归档的项目
  

• 目前已经归档的项目api
  

  

---

总结

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

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

---