網站後台要做客戶端API介面，介面文檔如何寫？

01-05

有一個網站外包項目，需求方是我這邊提的需求，現在網站項目要做客戶端app的介面數據，就是提供給app的API，外包公司問我需要提供多少API，要求我提供一份需要的API介面規範文檔；
我剛剛接觸產品經理，不太懂這個；請問這個流程有沒有問題；還有主要的問題是這個介面文檔如何寫？有沒有格式參考？請給我一個參考的案例；感激不盡
謝謝各位@

I am G.gladman

1. 一些全局的東西放在前面。

如：

1
介面規範介紹
本介面規範對XXXX手機客戶端介面操作，相關參數、響應和錯誤碼進行定義，所有提交及返回接收的變數均使用小寫。目前支持REST APP，並提供介面操作請求和響應範例。

如統一的報錯返回什麼信息：

REST錯誤響應

所有訪問當出現錯誤時，HTTP響應包含以下Header信息：
l Content-Type: application/json
l HTTP響應碼，3xx, 4xx, or 5xx

HTTP Body包含具體錯誤描述信息，如下例所示：
{「error」:{「code」:」NosuchUser」,「message」:」User
not exist」}}

還有就是什麼請求的url，請求頭SessionKey，編碼之類的統一說明。

2. 分類介面，詳細說明

如登陸介面：

3.4.1用戶登錄
介面說明
用戶登錄。
URL
XXXX/XXX
HTTP請求方式
POST

請求Headers
2 Date
請求參（下面是表格，不過知乎顯示不了）
參數名稱類型參數描述
loginname String 用戶名
password String 登錄密碼
mobiletype String 登錄的類型
token String 客戶端標識（IOS保存，不存在為空）

響應Headers
無特殊響應Header。
響應參數（下面是表格，不過知乎顯示不了）
參數名稱類型參數描述
userid Long 用戶ID
usernick String 用戶登錄名
sessionkey String 用戶會話key
示例

請求
XXXX
響應
{「usersession」:
{「userid」:」125」,
「usernck」:」 name 「,
」sessionkey」:」21232435353」,
}}

就這樣一個個介面說明白，開發人員看了也清楚。
3. 接下來一些特別的需求
如某些文件的訪問路徑等。
4. 最後是修訂歷史
版本號作者時間內容

0.1 XXXX 2014．02.10 創建

推薦使用http://apiary.io的api blueprint來定義介面規範，美觀簡潔

我們所接觸的項目，介面文檔一般是API提供方提供的，所以只能作為提供方來回答了，希望對你有幫助。

下面是自己以前製作的一份介面文檔的主要框架，僅供參考：

文檔信息

文檔名稱

文檔管理編號

保密級別

文檔類型

擴散範圍

適用範圍

版本變更記錄

版本說明時間修改人

1.0 新建文檔 2013-12-1 6某某某

1. 介面定義

介面說明

介面1 介面1說明

1.1介面1定義

介面調用請求說明

http請求方式：POST/FORM

編碼方式：UTF-8

https://xxxxx

示例（使用curl命令）：

curl -F resultFile=@/tmp/xxx -k https://xxx

參數說明

參數說明

參數1 參數1說明

返回值

正確情況下的返回：

&0& // 返回碼，返回碼詳細定義參見附錄

&&& // 返回碼描述信息

......

錯誤情況下的返回：

&1& // 返回碼，返回碼詳細定義參見附錄

&&& // 返回碼描述信息

2. 附錄

2.1 返回碼詳細定義

返回碼描述

0 請求成功

1 缺少用戶名或密碼

2 用戶名或密碼錯誤

最近也在頭痛這個，但是輸入，輸出，參數，異常，測試用例都準備，肯定沒錯的。

推薦下我司開發的 NEI 介面管理平台：https://nei.netease.com，介紹文章請戳：NEI 介面管理平台 - 知乎專欄，主要功能有：

1. 不只是 api 文檔管理，NEI 的視角是整個項目，更符合實際開發情況

2. 介面 Mock Server，方便前後端並行開發，極大地提高了生產力

3. 介面測試，後端開發自測，測試人員錄入測試用例，全方位保證介面交付質量

4. 工程規範，最大限度地自定義項目的初始化目錄結構，方便新項目啟動，還有其他更多功能等你來挖掘

關注這個問題很久，也一直在找相關工具，最近終於找到個好東西：

RAP v0.10 阿里的都在用這個

小幺雞，簡單好用的在線介面文檔管理系統

支持在線測試，經測試（可降低介面錯誤率）。

支持json，js，websocket，二進位測試。

推薦一個目前最火的在線 Api管理工具：支持在線調試，文檔生成，項目管理，體驗不錯。

http://apizza.cc?f=s9527

JApiDocs , 用 Java 開發者的首選啊～支持發布到 rap，想早點回家吃飯的就用它吧！

推薦使用Swagger

以Java Spring MVC 為例，寫API Controller代碼的同時，在每個方法中，編寫swagger的註解即可（描述每個參數的含義、介面說明等）。

然後自動生成在線的API介面文檔。

具體方法可以自行百度

客戶端和伺服器端的介面協議是非常重要的文檔。個人認為要產品經理來寫稍微有點牽強。

我覺得就可以參考sina微薄API的寫法，客戶端、服務端應該都能看明白。

感覺應該是程序猿寫的，不懂開發的產品寫肯定寫不出來啊

產品怎麼寫api文檔

也想學習一下介面文檔規範，一樓提供的blueprint看著很棒，正在研究，有機會討論一下。

spring io

GitHub - gongwalker/ApiManager: 介面文檔管理工具

簡單實用

不是產品寫的