后端接口功能開發(fā)完成后，接入接口的同事需要知道每個(gè)接口的功能炕横，以及請(qǐng)求需要帶哪些參數(shù)等源内，所以，提供接口文檔給別人查看就顯得非常必要了份殿；用Markdown寫文檔的好處在于文檔的排版整齊膜钓、格式統(tǒng)一，寫起文檔更加簡(jiǎn)單卿嘲、快速颂斜。關(guān)于 Markdown 的詳細(xì)語(yǔ)法，可以參考Markdown 語(yǔ)法說明拾枣。
??最近在 github 上開源了基于Markdown編寫的接口文檔項(xiàng)目api-doc沃疮，供大家參考使用；下面大概講解文檔的相關(guān)內(nèi)容：
1. 環(huán)境部署/安裝
文檔基于 gitbook 運(yùn)行的放前，所以需要配置 gitbook 的運(yùn)行環(huán)境忿磅，配置過程如下：
1.1 克隆源代碼
> git clone https://github.com/WongMinHo/api-doc.git
1.2. 配置本地運(yùn)行環(huán)境
1). 安裝npm
從官網(wǎng)下載源碼糯彬，解壓凭语，執(zhí)行如下命令安裝：
./configure
make
make install
2). 安裝gitbook
npm install gitbook-cli -g
如果安裝太慢，可以設(shè)置淘寶代理鏡像撩扒，執(zhí)行命令：
npm config set registry https://registry.npm.taobao.or
查看gitbook是否安裝成功：
gitbook -V
使用
進(jìn)入api-doc目錄似扔，執(zhí)行命令：
gitbook serve
瀏覽器打開：http://localhost:4000/
即可訪問文檔吨些。
2. 文檔使用說明
2.1版本歷史
| 日期 | 版本號(hào) | 作者 | 備注 |
|---|---|---|---|
| 2017.5.12 | 1.0 | MinHow | 新版本發(fā)布 |
2.2 文檔介紹
本文檔的接口遵循RESTful設(shè)計(jì)風(fēng)格...。
2.3接口約定
2.3.1 登錄認(rèn)證流程
基于JWT認(rèn)證機(jī)制炒辉，實(shí)現(xiàn)登錄認(rèn)證流程...豪墅。
2.3.2 Token 驗(yàn)證
Token訪問有效期為兩個(gè)小時(shí)，刷新有效期為兩周...黔寇。
注意事項(xiàng)：...偶器。
2.3.3 返回結(jié)果
所有返回結(jié)果以 JSON 格式返回；接口返回一共有三種情況：
- 操作成功后返回缝裤，范例：
{
"code": "200",//狀態(tài)碼
"msg": "SUCCESS"http://信息
}
- 成功返回?cái)?shù)據(jù)屏轰，范例：
{
"data": {//數(shù)據(jù)
"name": "minhow",
"age": "18"
},
"code": "200",//狀態(tài)碼
"msg": "SUCCESS"http://信息
}
- 錯(cuò)誤返回，范例：
{
"err_code": "1001",//錯(cuò)誤狀態(tài)碼
"err_msg": "認(rèn)證失敗憋飞，請(qǐng)重新登錄霎苗！"http://錯(cuò)誤信息
}
2.3.4 全局響應(yīng)狀態(tài)碼說明
| 狀態(tài)碼 | 說明 |
|---|---|
| 200 | 操作成功 |
| 1001 | 認(rèn)證失敗，請(qǐng)重新登錄榛做！ |
| 1002 | 參數(shù)不合法唁盏！ |
3. 目錄
文檔的接口目錄結(jié)構(gòu)，文檔中舉了三個(gè)案例检眯，如下：
1.1 認(rèn)證管理
?1.1.1 登錄
?1.1.2 刷新Token值
1.2 用戶管理
?1.2.1 個(gè)人中心
4. 接口說明
登錄案例如下：
1. 登錄
1.1 功能描述
提供手機(jī)號(hào)和密碼的登錄方式厘擂。
1.2 請(qǐng)求說明
請(qǐng)求方式：POST
請(qǐng)求URL ：login
1.3 請(qǐng)求參數(shù)
| 字段 | 字段類型 | 字段說明 |
|---|---|---|
| phone | int | 手機(jī)號(hào) |
| password | string | 密碼 |
1.4 返回結(jié)果
{
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vc2FsZS1hcGkuZGV2L2xvZ2luIiwiaWF0IjoxNDkxNTMyOTI4LCJleHAiOjE0OTIyNTI5MjgsIm5iZiI6MTQ5MTUzMjkyOCwianRpIjoiN1hCUXdwN1FHZmxUdHVVQiIsInV1aWQiOiI1MDZjYWY3MCJ9.FyyXagHtBfDBtMJZPV_hm2q6CVULpY63JPDGDHXc"
},
"code": "200",
"msg": "SUCCESS"
}
1.5 返回參數(shù)
| 字段 | 字段類型 | 字段說明 |
|---|---|---|
| token | string | token值 |
1.6 錯(cuò)誤狀態(tài)碼
| 狀態(tài)碼 | 說明 |
|---|---|
| 3001 | 其他認(rèn)證錯(cuò)誤信息！ |
| 3002 | 用戶不存在锰瘸！ |
| 3003 | 用戶名或密碼有誤驴党！ |
部分代碼如下：
## 1. 登錄
### 1.1 功能描述
提供手機(jī)號(hào)和密碼的登錄方式。
### 1.2 請(qǐng)求說明
> 請(qǐng)求方式：POST<br>
請(qǐng)求URL ：[login](#)
### 1.3 請(qǐng)求參數(shù)
字段 |字段類型 |字段說明
------------|-----------|-----------
phone |int |手機(jī)號(hào)
password |string |密碼
### 1.4 返回結(jié)果
```json
{
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vc2FsZS1hcGkuZGV2L2xvZ2luIiwiaWF0IjoxNDkxNTMyOTI4LCJleHAiOjE0OTIyNTI5MjgsIm5iZiI6MTQ5MTUzMjkyOCwianRpIjoiN1hCUXdwN1FHZmxUdHVVQiIsInV1aWQiOiI1MDZjYWY3MCJ9.FyyXagHtBfDBtMJZPV_hm2q6CVULpY63JPDGDHXc"
},
"code": "200",
"msg": "SUCCESS"
}
### 1.5 返回參數(shù)
字段 |字段類型 |字段說明
------------|-----------|-----------
token |string |token值
### 1.6 錯(cuò)誤狀態(tài)碼
狀態(tài)碼 |說明
------------|-----------
3001 |其他認(rèn)證錯(cuò)誤信息获茬！
3002 |用戶不存在港庄！
3003 |用戶名或密碼有誤！
更多的源碼內(nèi)容恕曲，請(qǐng)查看api-doc
