技術·文檔 | 標準API文檔規範 1.0

背景

隨着業務的發展，支撐平臺的項目也是愈來愈多。

同時，爲了讓業務系統更加清晰，會從整個平臺項目的架構體系，對系統業務水平拆分、垂直分層，產生了一系列平臺和子系統，並使用接口進行數據交互。

伴隨着業務的發展，接口文檔會愈來愈多。

那麼痛點在哪裏？

代碼和文檔不匹配，代碼接口更新，文檔不更新，且接口文檔內容和形式百花齊放，不便於理解。

擼碼一分鐘,對接三小時

爲了解決這些痛點，咱們定義了以下接口文檔規範，用於編寫API接口時的指導，以便於你寫出良好規範的API文檔。

API文檔概述

什麼是API

API（Application Programming Interface）即應用程序編程接口，是一些預先定義的函數，是鏈接客戶端與服務端的橋樑，能夠爲應用程序與開發人員提供基於某軟件或硬件得以訪問一組例程的能力，而又無需訪問源碼，或理解內部工做機制的細節。

什麼是API文檔

API文檔是面向API使用者對API功能、用法和版本等信息等詳盡描述，API文檔增長了API等易用性，是API開發者面向使用者對公開約束。

什麼是好的API文檔

好的API接口文檔對於使用者來講必須知足如下幾個點：

• 易學習：

有完善的文檔及提供儘量多的示例，文檔要遵循行業和國際標準，讓有經驗和背景的調用者能夠快速上手。

例如，定義國家代碼，要使用ISO-3316國家代碼標準中的國家代碼，中國是「CN」，而不是本身造一個「CHI」，以避免形成誤解。

• 易使用：

對於讀者來講，文檔沒有複雜的程序和業務細節，只要易於讀者學習便可。

靈活的API容許按字段排序、可自定義分頁、 排序和篩選等。一個完整的API意味着被指望的功能都包含在內。

• 難誤用：

詳細的錯誤提示，用戶可從文檔的閱讀中瞭解API的使用方法和誤區，不會在調用API的時候出現「驚喜」。

• 兼容性

API的升級要考慮向下兼容，文檔也要考慮先後一致。

例如儘可能避免在版本1是必填的參數，在版本2改成非必填，等等。

• 實時性

文檔也相應地要考慮隨着版本的更新而更新，且與服務一致。

避免客戶端根據老的文檔而請求新的接口而形成與預期不一致。

API文檔目錄

下面定義了標準的接口文檔目錄格式：

1.修訂歷史
2.接口描述
3.服務接入
    基本信息
    服務信息
4.請求和返回參數
    請求參數
    返回參數
5.成功和異常示例
    成功示例
        請求參數
        返回參數
    異常示例
        請求參數
        返回參數
6.狀態碼
    錯誤碼
    業務碼
複製代碼

API文檔示例

下面提供了標準的接口文檔的簡要示例，能夠在建立API文檔的時候參考此結構和示例。

修訂歷史

如下爲本文檔對修訂歷史，倒序排列。

原則上，不管API發生了任何定義、約束和功能上的變動，都應該體如今如下修訂歷史中，同時強烈建議在接口發生變動之後升級版本，並儘量保證向下兼容（即若是客戶端沒有更新API也能夠正常使用以前的功能）。

日期	版本	說明	修訂人
2019-12-12	1.0.3	這裏是修訂說明	劉備
2019-12-12	1.0.2	這裏是修訂說明	張飛
2019-12-12	1.0.1	這裏是修訂說明	劉備

接口描述

如下爲文檔的概要描述，簡要說明了此接口提供的能力、覆蓋的業務場景、相關的系統角色等。

服務接入

此處描述了接口的形式（RPC、HTTP等）、接口的地址、客戶端等配置等信息。

基本信息

接口地址	com.example.api/transfer/v1/
請求方式	HTTP / POST
是否須要受權	是
調用頻率限制	900次/秒

服務信息

若是是請求RPC接口，須要增長以下描述。

• 服務AppId：AppPAyService

• 接口：com.example.pay.TransferService

• 方法：transfer

• maven依賴

開發聯調時使用SAPSHOT版本,上UAT前須要更換最新RELEASE版本

<dependency>
  <groupId>com.example.pay</groupId>
  <artifactId>pay-transfer</artifactId>
  <version>最新RELEASE版本</version>
</dependency>
複製代碼

• 接口定義

public interface TransferService {
    Response<Result> transfer(Request request);
}
複製代碼

數據模型

一個完整的數據模型定義應包括：

• 路徑與查詢字符串參數模型
• 請求體參數模型
• 響應體參數模型

下面列舉了請求和返回參數的數據模型定義示例，其中「變量名|類型|是否必填」是組成一個參數的最小數據集（MDS），即一個完成的參數定義至少要有這三個信息。

請求參數

字段名	變量名	類型	是否必填	最大長度	描述	示例值
商戶號	mchId	String	是	32	系統分配的商戶帳戶	100098
金額	amount	Int	是		轉帳金額，單位：分	200

返回參數

字段名	變量名	類型	是否必填	最大長度	描述	示例值
流水號	txnId	String	否	32	交易流水號	2019022018061908
狀態碼	status	Int	是	1	是否成功,0:成功,1:失敗	1
錯誤碼	errorCode	Int	否	4	系統分配的商戶帳戶	401
錯誤描述	desc	String	否	128	備註說明	操做成功

對接示例

成功示例

請求參數

{
    "mchId":"1000008",
    "amount":900
}
複製代碼

返回參數

{
    "txnId":"2019022018061909",
    "status":0
}
複製代碼

異常示例

請求參數

{
    "mchId":"100000",
    "amount":100
}
複製代碼

返回參數

{
    "status":1
    "errorCode":404,
    "desc":"商戶不存在"
}
複製代碼

狀態碼

錯誤碼

錯誤代碼	描述	緣由	解決方案
401	沒有受權	客戶端IP沒有受權	在服務端進行受權
404	商戶不存在	非系統商戶	檢查是不是分配的商戶號

業務碼

業務碼	描述	說明
ACCEPT	交易接受	交易被系統接受
REJECT	交易拒絕	此交易被系統拒絕