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 } } } ~~~ > ### 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": {} } ~~~ ```