編寫一份基本的接口文檔要注意以下幾點：
1.一定要有版本號，因爲基本上對應的接口都是剛開發或者待開發的（已經正常使用的接口也不需要你來寫文檔）不可能一次提供最終版，方便後續更改，同時避免因爲修改多次導致雙方使用不一樣的文檔而出錯。
2.要有目錄和時間（創建時間，修改時間）
3.接口文檔最重要的是接口的詳細信息，基本上滿足以下幾點就可以了：
· 接口名稱
· 功能說明
· 提供方，調用方
· 接口調用方式
· 接口調用地址（必要時分別給出測試和生產的）
· 一個調用的樣例和返回的樣例
|
接口詳情 |
|
|
地址 |
http://www.baidu.com （正式環境） |
|
請求方式 |
GET |
|
參數 |
是否必填 |
說明 |
|
idfa |
是 |
廣告標識符，只支持單個查詢 |
|
source |
是 |
渠道來源，具體值在接入時再進行分配 |
|
返回結果 |
格式 |
JSON |
|
狀態碼 |
10000 |
success（調用成功） |
|
|
10001 |
param error(參數錯誤) |
|
|
10002 |
query failed（查詢失敗） |
|
|
10010 |
access prohibited(訪問拒絕) |
具體返回結果舉例：
1、查詢成功
{
"state": 10000,
"message": "success",
"data": {
"BD239708-2874-417C-8292-7E335A537FAD": 1 //已經存在
}
}
{
"state": 10000,
"message": "success",
"data": {
"BD239708-2874-417C-8292-7E335A537FAD": 0 //不存在
}
}
2、接口調用失敗
{
"state": 10010,
"message": "access prohibited",
"data": [
]
}
4.附錄
一些參數的枚舉編碼表，參考資料等等。