如何寫好接口文檔？

1 HTTP攜帶信息的方式

• url
• headers
• body: 包括請求體，響應體

2 分離通用信息

通常來講，headers裏的信息都是通用的，能夠提早說明，做爲默認參數

3 路徑中的參數表達式

URL中參數表達式使用mustache的形式，參數包裹在雙大括號之中{{paramName}}

例如：

• /api/user/{{userId}}
• /api/user/{{userType}}?age={{age}}&gender={{gender}}

4 數據模型定義

數據模型定義包括：

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

數據模型的最小數據集：

• 名稱
• 是否必須
• 說明

「最小數據集」（MDS）是指經過收集最少的數據，較好地掌握一個研究對象所具備的特色或一件事情、一份工做所處的狀態，其核心是針對被觀察的對象創建起一套精簡實用的數據指標。最小數據集的概念起源於美國的醫療領域。最小數據集的產生源於信息交換的須要，就比如上下級質量技術監督部門之間、企業與質量技術監督部門之間、質量技術監督部門與社會公衆之間都存在着信息交換的需求。

一些文檔裏可能會加入字段的類型，可是我認爲這是不必的。覺得HTTP傳輸的數據每每都須要序列化，大部分數據類型都是字符串。一些特殊的類型，例如枚舉類型的字符串，能夠在說明裏描述。

另外：數據模型很是建議使用表格來表現。

舉個栗子?：

名稱	是否必須	說明
userType	是	用戶類型。commom表示普通用戶，vip表示vip用戶
age	否	用戶年齡
gender	否	用戶性別。1表示男，0表示女

5 請求示例

// general 
POST http://www.testapi.com/api/user

// request payload
{
    "name": "qianxun",
    "age": 14,
    "like": ["music", "reading"],
    "userType": "vip"
}

// response
{
    "id": "asdkfjalsdkf"
}

6 異常處理

異常處理最小數據集

• 狀態碼
• 說明
• 解決方案

舉個栗子?：

狀態碼	說明	解決方案
401	用戶名密碼錯誤	檢查用戶名密碼是否正確
424	超過最大在線數量	請在控制檯修改最大在線數量

以前我一直不想把解決方案加入異常處理的最小數據集，可是對於不少開發者來講，即便它知道424表明超過最大在線數量。若是你不告訴若是解決這個問題，那麼他們可能就會直接來問你。因此最好可以一步到位，直接告訴他應該如何解決，這樣省時省力。

7 如何組織？

7.1 一個建立用戶的例子：建立用戶

1 請求示例

// general 
POST http://www.testapi.com/api/user/vip/?token=abcdefg

// request payload
{
    "name": "qianxun",
    "age": 14,
    "like": ["music", "reading"]
}

// response
{
    "id": "asdkfjalsdkf"
}

2 路徑與查詢字符串參數模型
POST http://www.testapi.com/api/user/{{userType}}/?token={{token}}

名稱	是否必須	說明
userType	是	用戶類型。commom表示普通用戶，vip表示vip用戶
token	是	認證令牌

3 請求體參數模型

名稱	是否必須	說明
name	是	用戶名。4-50個字符
age	否	年齡
like	否	愛好。最多20個

4 響應體參數模型

名稱	說明
id	用戶id

5 異常處理

狀態碼	說明	解決方案
401	token過時	請從新申請token
424	超過最大在建立人數	請在控制檯修改最大建立人數

7.2 這樣組織的緣由

1. 請求示例: 請求示例放在第一位的緣由是，要用最快的方式告訴開發者，這個接口應該如何請求
2. 路徑與查詢字符串參數模型： 使用mustache包裹參數
3. 請求體參數模型：若是沒有請求體，能夠不寫
4. 響應體參數模型：
5. 異常處理

8 文檔提供的形式

文檔建議由一下兩種形式，在線文檔，pdf文檔。

• 在線文檔

  • 更新方便
  • 易於隨時閱讀
  • 易於查找

• pdf文檔

  • 內容表現始終如一，不依賴文檔閱讀器
  • 文檔只讀，不會被輕易修改

其中因爲是面對第三方開發者，公開的在線文檔必須提供；因爲某些特殊的緣由，可能須要提供文件形式的文檔，建議提供pdf文檔。固然，如下的文檔形式是很是不建議提供的：

• word文檔
• markdown文檔

word文檔和markdown文檔有如下缺點：

• 文檔的表現形式很是依賴文檔查看器：各個版本的word文檔對word的表現形式差別很大，可能在你的電腦上內容表現很好的文檔，到別人的電腦上就會一團亂麻；另外markdown文件也是如此。並且markdown中引入文件只能依靠圖片連接，若是文檔中含有圖片，極可能會出現圖片丟失的狀況。
• 文檔沒法只讀：文檔沒法只讀，就有可能會被第三方開發者在不經意間修改，那麼文檔就沒法保證其準確性了。

總結一下，文檔形式的要點：

• 只讀性：保證文檔不會被開發者輕易修改
• 一致性：保證文檔在不一樣設備，不一樣文檔查看器上內容表現始終如一
• 易於版本管理：文檔即軟件（DAAS: Document as a Software），通常意義上說軟件 = 數據 + 算法, 可是我認爲文檔也是一種組成軟件的重要形式。既然軟件須要版本管理，文檔的版本管理也是比不可少的。