API 文档类型是看云特有的一种文档类型,可以快速定义和生成产品或项目的`API`文档。 [ [点击查看示例API文档](http://www.kancloud.cn/shuai/api_demo/67290) ] ## 创建API文档 选择创建API 文档类型后,表单如下: ![document/2015-09-25/560551f627d55](http://box.kancloud.cn/document_2015-09-25_560551f627d55.png) API相关设置包括设置**基础URL**和**添加Header**(这一步可以先不填,以后直接在编辑模式下面选择右上角的文档设置进行更改) 点击更多设置,可以看到更多的设置参数: ![document/2015-09-25/560552b4b8836](http://box.kancloud.cn/document_2015-09-25_560552b4b8836.png) ## 定义API文档 创建的API文档后,会做一些初始化内容,如图所示: ![document/2015-09-25/56055347b24c7](http://box.kancloud.cn/document_2015-09-25_56055347b24c7.png) 我们来完成第一个API接口的文档,定义分成几个部分: ## 1 全局设置 ![](https://box.kancloud.cn/2015-11-12_564443aa290ac.png) 如下: ~~~ { "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": {} } ~~~ ```