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": []
}