研發團隊如何寫好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。

有了規範更能減小溝通偏差,提升工做效率

---

微信公衆號：碼農商業參謀