接口文檔規範

什麼是接口

接口全稱是應用程序編程接口，是應用程序重要的組成部分。接口能夠是一個功能，例如天氣查詢，短信羣發等，接口也能夠是一個模塊，例如登陸驗證。接口經過發送請求參數至接口url，通過後臺代碼處理後，返回所需的結果。

爲何須要編寫接口文檔

因爲接口所包含的內容比較細，在項目中經常須要使用接口文檔。研發人員能夠根據接口文檔進行開發、協做，測試人員能夠根據接口文檔進行測試，系統也須要參照接口文檔進行維護等。

接口文檔規範

接口文檔內容可大體分爲請求前、請求後內容。
請求前的內容包括接口的基本信息。內容以下：
一、接口協議。如http、https、tcp協議等。
二、接口請求方式。常見的請求方式有get、post，還有put、delete等。
三、接口url。接口請求的url
四、接口名稱。用於識別接口。
五、接口請求頭部。包含請求頭部參數、參數說明。
六、接口請求體。包含請求參數、參數說明，與參數格式。
七、

請求後的內容包括接口響應後的結果。內容以下：
一、響應結果。包括返回頭部、返回結果參數，參數值說明，參數類型。
二、示例。成功示例與失敗示例，與對應的狀態碼，例如成功返回狀態碼200。
三、

以上是接口文檔必要的基本信息，在項目中爲了方便問題追溯與後期維護，接口文檔還須要記錄接口狀態、版本、負責人、建立人、最後編輯人、時間、接口說明等信息。最終一份完善的api文檔以下所示。

接口文檔編寫須要花費必定的精力，隨着項目不斷更新，接口文檔也逐漸成爲項目的核心文件。寫好接口文檔是應用程序發展的基礎。
演示工具爲Eolinker，使用地址：www.eolinker.com