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