API 文档类型是看云特有的一种文档类型，可以快速定义和生成产品或项目的`API`文档。 \[[点击查看示例API文档](http://www.kancloud.cn/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": {}
}
~~~
