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

創建API文檔

選擇創建API 文檔類型后，會彈出如下表單：

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

如果選擇開啟API在線調試的話，可以支持API在線調試功能（前提是你的基礎URL已經部署了api）。

定義API文檔

創建的API文檔后，會做一些初始化內容，如圖所示：

我們來完成第一個API接口的文檔，定義分成幾個部分：

1 全局設置

如下：

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

url

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

headers(可選)

是一個數組，測試時作為http headers提交到服務器

params(可選)

所有api都有都公共參數，是一個數組，每個數組元素有如下屬性：
default：默認值
desc：字段說明
name：字段名
required：是否必填
type：字段類型

explore

是否開啟在線調試功能，有些api可能需要內網環境，無法在線調試，則可關閉此項

以上配置項可以分組配置
如下：

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

2 API定義

API的標簽格式為一組+++
如：

+++
get:/url
*id=默認值#說明文字
name#說明文字
<<<
success
{
    "errNum": 0,
    "retMsg": "success",
    "retData": {}
}
<<<
error
這里填寫錯誤的返回碼
以此類推，每個狀態使用 <<< 分割,
第一行添加狀態名稱
+++

在開始的+++后面可以跟上此條api使用的配置分組名稱，不寫則為默認的default分組，或者上面配置沒有分組的時候也可以不填
比如：

+++second
get:/url
*id=默認值#說明文字
name#說明文字
<<<
success
{
    "errNum": 0,
    "retMsg": "success",
    "retData": {}
}
<<<
error
這里填寫錯誤的返回碼
以此類推，每個狀態使用 <<< 分割,
第一行添加狀態名稱
+++

3 API接口方法請求類型和URL地址

定義格式： [請求類型:]URL地址
例如：

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

如果沒有添加請求類型的話，默認就是get請求。

4 API接口方法的參數列表

接口請求類型和URL地址后緊隨著就是參數列表定義，每一行定義一個接口參數，定義格式：

*[參數類型:]參數名稱=默認值#參數說明

例如：

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

參數名稱前面如果帶*號表示該參數為必須。

默認的參數類型是string，如果需要指定類型，可以使用：

*int:id=0#用戶ID

參數類型僅僅作為傳值參考，所有請求的參數都是首先作為string傳入后自行轉換處理。

5 返回結果定義

返回結果可以根據不同的狀態需要定義，返回結果以 <<<標識開頭，例如：

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