API 文档类型是看云特有的一种文档类型,可以快速定义和生成产品或项目的API文档。 [ [点击查看示例API文档](http://www.kancloud.cn/shuai/api_demo/67290) ]

创建API文档

选择创建API 文档类型后,表单如下:

document/2015-09-25/560551f627d55

API相关设置包括设置基础URL添加Header(这一步可以先不填,以后直接在编辑模式下面选择右上角的文档设置进行更改)

点击更多设置,可以看到更多的设置参数:

document/2015-09-25/560552b4b8836

定义API文档

创建的API文档后,会做一些初始化内容,如图所示:

document/2015-09-25/56055347b24c7

我们来完成第一个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的标签格式为~~~[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#用户昵称

参数名称前面如果带*号表示该参数为必须。

默认的参数类型是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": {}
}
~~~