1 HTTP攜帶信息的方式

• url

• headers

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

2 分離通用信息

一般來說，headers里的信息都是通用的，可以提前說明，作為默認參數

3 路徑中的參數表達式

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

例如：

• /api/user/{{userId}}

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

4 數據模型定義

數據模型定義包括：

• 路徑與查詢字符串參數模型

• 請求體參數模型

• 響應體參數模型

數據模型的最小數據集：

• 名稱

• 是否必須

• 說明

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

一些文檔里可能會加入字段的類型，但是我認為這是沒必要的。以為HTTP傳輸的數據往往都需要序列化，大部分數據類型都是字符串。一些特殊的類型，例如枚舉類型的字符串，可以在說明里描述。

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

舉個栗子

以上就是寫好接口文檔的方法的詳細內容，更多請關注php中文網其它相關文章！