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
}
}
}
~~~
>[info] ###url
> api提交的基礎url，如這里設置的是`http://www.kancloud.com`你api定義到URL地址是`/user`,那么此條api實際提交的地址是`http://www.kancloud.com/user`
>[info] ###headers(可選)
> 是一個數組，測試時作為http headers提交到服務器
>[info] ###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 // 刪除博客
~~~
>[info] 如果沒有添加請求類型的話，默認就是get請求。
## 4 API接口方法的參數列表
接口請求類型和URL地址后緊隨著就是參數列表定義，每一行定義一個接口參數，定義格式：
*[參數類型:]參數名稱=默認值#參數說明
例如：
*id=0#用戶ID
name#用戶昵稱
>[info] 參數名稱前面如果帶\*號表示該參數為必須。
默認的參數類型是string，如果需要指定類型，可以使用：
*int:id=0#用戶ID
>[info] 參數類型僅僅作為傳值參考，所有請求的參數都是首先作為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": {}
}
~~~
