markdown 文档服务器,markdown进阶语法--API文档

[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

这里填写错误的返回码

以此类推，每个状态使用 <<< 分割,

第一行添加状态名称

~~~

```