一些剛開始寫接口文檔的服務端同學，很容易按著代碼的思路去編寫接口文檔，這讓客戶端同學或者是服務對接方技術人員經(jīng)常吐槽，看不懂接口文檔。這篇文章提供一個常規(guī)接口文檔的編寫方法，給大家參考。
一、請求參數(shù)
- 請求方法
- GET 用于獲取數(shù)據(jù)
- POST 用于更新數(shù)據(jù)
- PUT 用于新增數(shù)據(jù)
- DELETE用于刪除數(shù)據(jù)
- 其他 其他的請求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS
- URL
url表示了接口的請求路徑。路徑中可以包含參數(shù)，稱為地址參數(shù)，如/user/{id}，其中id作為一個參數(shù)。
- HTTP Header
HTTP Header用于此次請求的基礎信息，在接口文檔中以K-V方式展示，其中Content-Type則是一個非常必要的header，它描述的請求體的數(shù)據(jù)類型。
常用的content-type：
- Application/x-www-form-urlencoded
- application/json
- application/xml
- multipart/form-data
- HTTP Body
描述http body，依賴于body中具體的數(shù)據(jù)類型。如果body中的數(shù)據(jù)是對象類型。則需要描述對象中字段的名稱、類型、長度、不能為空、默認值、說明。以表格的方式來表達最好。
示例：
二、響應參數(shù)
- 響應 HTTP Body
響應body同請求body一樣，需要描述請清除數(shù)據(jù)的類型。
另外，如果服務會根據(jù)不同的http status code 返回不同的數(shù)據(jù)結(jié)構(gòu)， 也需要針對不同的http status code對內(nèi)容進行描述。
三、接口說明
說明接口的應用場景，特別的注意點，比如，接口是否冪等、處理是同步方式還是異步方式等。
筆者平時使用的是 http://www.docway.net（以前叫小幺雞） 這個網(wǎng)站寫接口文檔，方便保存和共享。
四、示例
上個示例（重點都用紅筆圈出來，記牢了）：
