API 文檔類型是看云特有的一種文檔類型，可以快速定義和生成產(chǎn)品或項(xiàng)目的API文檔。 [ 點(diǎn)擊查看示例API文檔 ]

創(chuàng)建API文檔

選擇創(chuàng)建API 文檔類型后，會(huì)彈出如下表單：

API相關(guān)設(shè)置包括設(shè)置基礎(chǔ)URL和添加Header（這一步可以先不填，以后直接在編輯模式下面選擇右上角的文檔設(shè)置進(jìn)行更改）

如果選擇開(kāi)啟API在線調(diào)試的話，可以支持API在線調(diào)試功能（前提是你的基礎(chǔ)URL已經(jīng)部署了api）。

定義API文檔

創(chuàng)建的API文檔后，會(huì)做一些初始化內(nèi)容，如圖所示：

document/2015-09-25/56055347b24c7

我們來(lái)完成第一個(gè)API接口的文檔，定義分成幾個(gè)部分：

1 全局設(shè)置


如下：

{
    "plugins": [
        "api",
        "highlight"
    ],
    "pluginsConfig": {
        "api": {
                "url": "http://www.kancloud.com",
                "headers": {
                    "key1":"value1"
                },
                "params":[
                     {
                        "default": "默認(rèn)值",
                        "desc": "說(shuō)明文字",
                        "name": "iid",
                        "required": true,
                        "type": "string"
                     }
                 ],
                "explore":true
            }
    }
}

url

api提交的基礎(chǔ)url，如這里設(shè)置的是http://www.kancloud.com你api定義到URL地址是/user ,那么此條api實(shí)際提交的地址是http://www.kancloud.com/user

headers(可選)

是一個(gè)數(shù)組，測(cè)試時(shí)作為http headers提交到服務(wù)器

params(可選)

所有api都有都公共參數(shù)，是一個(gè)數(shù)組，每個(gè)數(shù)組元素有如下屬性：
default：默認(rèn)值
desc：字段說(shuō)明
name：字段名
required：是否必填
type：字段類型

explore

是否開(kāi)啟在線調(diào)試功能，有些api可能需要內(nèi)網(wǎng)環(huán)境，無(wú)法在線調(diào)試，則可關(guān)閉此項(xiàng)

以上配置項(xiàng)可以分組配置
如下：

{
    "plugins": [
        "api",
        "highlight"
    ],
    "pluginsConfig": {
        "api": {
                "default":{
                    "url": "http://www.kancloud.com",
                    "headers": {
                        "key1":"value1"
                    },
                    "params":[
                         {
                            "default": "默認(rèn)值",
                            "desc": "說(shuō)明文字",
                            "name": "iid",
                            "required": true,
                            "type": "string"
                         }
                     ],
                    "explore":true
                },
                "second":{
                    "url": "http://www.kancloud.com",
                    "headers": {
                        "key2":"value2"
                    },
                    "explore":true
                }
            }
    }
}

2 API定義

API的標(biāo)簽格式為一組+++
如：

+++
get:/url
*id=默認(rèn)值#說(shuō)明文字
name#說(shuō)明文字
<<<
success
{
    "errNum": 0,
    "retMsg": "success",
    "retData": {}
}
<<<
error
這里填寫(xiě)錯(cuò)誤的返回碼
以此類推，每個(gè)狀態(tài)使用 <<< 分割,
第一行添加狀態(tài)名稱
+++

在開(kāi)始的+++后面可以跟上此條api使用的配置分組名稱，不寫(xiě)則為默認(rèn)的default分組，或者上面配置沒(méi)有分組的時(shí)候也可以不填
比如：

+++second
get:/url
*id=默認(rèn)值#說(shuō)明文字
name#說(shuō)明文字
<<<
success
{
    "errNum": 0,
    "retMsg": "success",
    "retData": {}
}
<<<
error
這里填寫(xiě)錯(cuò)誤的返回碼
以此類推，每個(gè)狀態(tài)使用 <<< 分割,
第一行添加狀態(tài)名稱
+++

3 API接口方法請(qǐng)求類型和URL地址

定義格式： [請(qǐng)求類型:]URL地址
例如：

get:/api/blog // 獲取博客
post:/api/blog // 發(fā)布博客
put:/api/blog  // 更新博客
delete:/api/blog // 刪除博客

如果沒(méi)有添加請(qǐng)求類型的話，默認(rèn)就是get請(qǐng)求。

4 API接口方法的參數(shù)列表

接口請(qǐng)求類型和URL地址后緊隨著就是參數(shù)列表定義，每一行定義一個(gè)接口參數(shù)，定義格式：

*[參數(shù)類型:]參數(shù)名稱=默認(rèn)值#參數(shù)說(shuō)明

例如： 

*id=0#用戶ID
name#用戶昵稱

參數(shù)名稱前面如果帶*號(hào)表示該參數(shù)為必須。

默認(rèn)的參數(shù)類型是string，如果需要指定類型，可以使用：

*int:id=0#用戶ID

參數(shù)類型僅僅作為傳值參考，所有請(qǐng)求的參數(shù)都是首先作為string傳入后自行轉(zhuǎn)換處理。

5 返回結(jié)果定義

返回結(jié)果可以根據(jù)不同的狀態(tài)需要定義，返回結(jié)果以 <<<標(biāo)識(shí)開(kāi)頭，例如：

<<<
success
{
    "errNum": 0,
    "retMsg": "success",
    "retData": {
        "city": "洛陽(yáng)",
        "time": "2015-09-09T16:00:00Z",
        "aqi": 77,
        "level": "良",
        "core": "顆粒物(PM10)"
    }
}
<<<
error
{
    "errNum": 0,
    "retMsg": "success",
    "retData": []
}