[toc] # 什么是API文档? > API文档类型是`看云特有的一种文档类型`，可以`快速定义和生成`产品或项目的API文档 # API文档长什么样? 官方demo [百度空气质量Api](https://www.kancloud.cn/shuai/api_demo/67274) [成语查询Api](https://www.kancloud.cn/shuai/api_demo/67276) # 让你的文档支持api语法 修改文档配置 ```json { "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 >[success] headers(可选) > 是一个数组，测试时作为http headers提交到服务器 >[danger] params(可选) > 所有api都有都公共参数，是一个数组，每个数组元素有如下属性： > >>[danger] default：默认值 >> desc：字段说明 >> name：字段名 >> required：是否必填 >> type：字段类型 >[warning] explore > 是否开启在线调试功能，有些api可能需要内网环境，无法在线调试，则可关闭此项 # 编写一个`用户登录/注册二合一`接口 流程图 ```[flow] st=>start: Start e=>end: End 接收用户名和密码=>operation: 接收用户名和密码 使用用户名查询数据库=>operation: 使用用户名查询数据库 数据库中是否有数据=>condition: 数据库中是否有数据? 走登录逻辑=>operation: 走登录逻辑 走注册逻辑=>operation: 走注册逻辑 密码是否正确=>condition: 密码是否正确? 把用户名和密码写入数据库=>inputoutput: 把用户名和密码写入数据库 st->接收用户名和密码->使用用户名查询数据库->数据库中是否有数据 数据库中是否有数据(yes)->走登录逻辑->密码是否正确 数据库中是否有数据(no)->走注册逻辑->把用户名和密码写入数据库->e 密码是否正确(yes)->e 密码是否正确(no,down)->接收用户名和密码 ``` 接口实例 ~~~[api] post:/justForTest/api/user/userLogin *string:user_name=15612345678#用户手机号 *string:user_pwd#密码 <<< success { "ret": 0, # 返回状态码 "data": { "user_id": 1 // 用户id }, } <<< error { "success": 0, // 请求成功! "user_name_wrong": 1, // 密码不正确! "insert_wrong": 2, // 数据库写入用户信息失败! "query_wrong": 3, // 获取用户信息失败! } ~~~ 接口代码 ``` ~~~[api] post:/justForTest/api/user/userLogin *string:user_name=15612345678#用户手机号 *string:user_pwd#密码 <<< success { "ret": 0, # 返回状态码 "data": { "user_id": 1 // 用户id }, } <<< error { "success": 0, // 请求成功! "user_name_wrong": 1, // 密码不正确! "insert_wrong": 2, // 数据库写入用户信息失败! "query_wrong": 3, // 获取用户信息失败! } ~~~ ``` # 代码语法分析 ``` ~~~[api] get:/url *id=默认值#说明文字 name#说明文字 <<< success { "errNum": 0, "retMsg": "success", "retData": {} } <<< error 这里填写错误的返回码 以此类推，每个状态使用 <<< 分割, 第一行添加状态名称 ~~~ ```