API 文檔類型是看云特有的一種文檔類型，可以快速定義和生成產品或項目的`API`文檔。 [ [點擊查看示例API文檔](http://www.hmoore.net/shuai/api_demo/67290) ] ## 創建API文檔 選擇創建API 文檔類型后，表單如下：  API相關設置包括設置**基礎URL**和**添加Header**（這一步可以先不填，以后直接在編輯模式下面選擇右上角的文檔設置進行更改） 點擊更多設置，可以看到更多的設置參數：  ## 定義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`：字段類型 >[success] ### explore 是否開啟在線調試功能，有些api可能需要內網環境，無法在線調試，則可關閉此項 　 >[warning]以上配置項可以分組配置 如下： ~~~ { "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的標簽格式為`~~~[api]` 如： ``` ~~~[api] get:/url *id=默認值#說明文字 name#說明文字 <<< success { "errNum": 0, "retMsg": "success", "retData": {} } <<< error 這里填寫錯誤的返回碼 以此類推，每個狀態使用 <<< 分割, 第一行添加狀態名稱 ~~~ ``` 在開始的`[api]`后面可以跟上此條api使用的配置分組名稱，不寫則為默認的`default`分組，或者上面配置沒有分組的時候也可以不填 比如： ``` ~~~[api: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#用戶昵稱 ~~~ >[info] 參數名稱前面如果帶*號表示該參數為必須。 默認的參數類型是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": [] } ~~~ ### 用戶認證 在插件配置里添加`security`參數，比如 ~~~ { "plugins": [ "api", "highlight" ], "pluginsConfig": { "api": { "url": "http://www.kancloud.com", "headers": { "key1":"value1" }, "params":[ { "default": "默認值", "desc": "說明文字", "name": "iid", "required": true, "type": "string" } ], "explore":true, "security":{ "type":"apiKey", // 必填 目前支持 apiKey和oauth2 兩種，apiKey表示添加一個額外的參數用于認證,oauth2表示使用Bearer Token的方式認證 "in":"query", // type為apiKey時有效，可為query和header兩種，query表示參數添加到請求的url里，header表示參數添加到header里 "name":"token",// type為apiKey時有效，用于認證權限的參數名 "default":"bbb"// 默認值 } } } } ~~~ 如果某條api不需要身份認證 可以使用分組配置或者在那條url前面添加`!` 比如 ``` ~~~[api] !get:/url *id=默認值#說明文字 name#說明文字 <<< success { "errNum": 0, "retMsg": "success", "retData": {} } ~~~ ```