1 HTTP攜帶信息的方式

• url

• headers

• body: 包括請(qǐng)求體，響應(yīng)體

2 分離通用信息

一般來說，headers里的信息都是通用的，可以提前說明，作為默認(rèn)參數(shù)

3 路徑中的參數(shù)表達(dá)式

URL中參數(shù)表達(dá)式使用mustache的形式，參數(shù)包裹在雙大括號(hào)之中{{paramName}}

例如：

• /api/user/{{userId}}

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

4 數(shù)據(jù)模型定義

數(shù)據(jù)模型定義包括：

• 路徑與查詢字符串參數(shù)模型

• 請(qǐng)求體參數(shù)模型

• 響應(yīng)體參數(shù)模型

數(shù)據(jù)模型的最小數(shù)據(jù)集：

• 名稱

• 是否必須

• 說明

“最小數(shù)據(jù)集”（MDS）是指通過收集最少的數(shù)據(jù)，較好地掌握一個(gè)研究對(duì)象所具有的特點(diǎn)或一件事情、一份工作所處的狀態(tài)，其核心是針對(duì)被觀察的對(duì)象建立起一套精簡(jiǎn)實(shí)用的數(shù)據(jù)指標(biāo)。最小數(shù)據(jù)集的概念起源于美國(guó)的醫(yī)療領(lǐng)域。最小數(shù)據(jù)集的產(chǎn)生源于信息交換的需要，就好比上下級(jí)質(zhì)量技術(shù)監(jiān)督部門之間、企業(yè)與質(zhì)量技術(shù)監(jiān)督部門之間、質(zhì)量技術(shù)監(jiān)督部門與社會(huì)公眾之間都存在著信息交換的需求。

一些文檔里可能會(huì)加入字段的類型，但是我認(rèn)為這是沒必要的。以為HTTP傳輸?shù)臄?shù)據(jù)往往都需要序列化，大部分?jǐn)?shù)據(jù)類型都是字符串。一些特殊的類型，例如枚舉類型的字符串，可以在說明里描述。

另外：數(shù)據(jù)模型非常建議使用表格來表現(xiàn)。

舉個(gè)栗子

以上就是寫好接口文檔的方法的詳細(xì)內(nèi)容，更多請(qǐng)關(guān)注php中文網(wǎng)其它相關(guān)文章！