寫好介面文件的方法

本文主要和大家分享如何寫好介面文件的方法，希望能幫助大家寫好一個介面文件。

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中文網其他相關文章！