后端接口功能开发完成后，接入接口的同事需要知道每个接口的功能，以及请求需要带哪些参数等，所以，提供接口文档给别人查看就显得非常必要了；用Markdown写文档的好处在于文档的排版整齐、格式统一，写起文档更加简单、快速。关于 Markdown 的详细语法，可以参考Markdown 语法说明。
最近在 github 上开源了基于Markdown编写的接口文档项目api-doc，供大家参考使用；下面大概讲解文档的相关内容：
1. 环境部署/安装
文档基于 gitbook 运行的，所以需要配置 gitbook 的运行环境，配置过程如下：
1.1 克隆源代码
> git clone https://github.com/WongMinHo/api-doc.git
1.2. 配置本地运行环境
1). 安装npm
从官网下载源码，解压，执行如下命令安装：
./configure
make
make install
2). 安装gitbook
npm install gitbook-cli -g
如果安装太慢，可以设置淘宝代理镜像，执行命令：
npm config set registry https://registry.npm.taobao.or
查看gitbook是否安装成功：
gitbook -V
使用
进入api-doc目录，执行命令：
gitbook serve
浏览器打开：http://localhost:4000/
即可访问文档。
2. 文档使用说明
2.1版本历史
| 日期 | 版本号 | 作者 | 备注 |
|---|---|---|---|
| 2017.5.12 | 1.0 | MinHow | 新版本发布 |
2.2 文档介绍
本文档的接口遵循RESTful设计风格...。
2.3接口约定
2.3.1 登录认证流程
基于JWT认证机制，实现登录认证流程...。
2.3.2 Token 验证
Token访问有效期为两个小时，刷新有效期为两周...。
注意事项：...。
2.3.3 返回结果
所有返回结果以 JSON 格式返回；接口返回一共有三种情况：
- 操作成功后返回，范例：
{
"code": "200",//状态码
"msg": "SUCCESS"//信息
}
- 成功返回数据，范例：
{
"data": {//数据
"name": "minhow",
"age": "18"
},
"code": "200",//状态码
"msg": "SUCCESS"//信息
}
- 错误返回，范例：
{
"err_code": "1001",//错误状态码
"err_msg": "认证失败，请重新登录！"//错误信息
}
2.3.4 全局响应状态码说明
| 状态码 | 说明 |
|---|---|
| 200 | 操作成功 |
| 1001 | 认证失败，请重新登录！ |
| 1002 | 参数不合法！ |
3. 目录
文档的接口目录结构，文档中举了三个案例，如下：
1.1 认证管理
1.1.1 登录
1.1.2 刷新Token值
1.2 用户管理
1.2.1 个人中心
4. 接口说明
登录案例如下：
1. 登录
1.1 功能描述
提供手机号和密码的登录方式。
1.2 请求说明
请求方式：POST
请求URL ：login
1.3 请求参数
| 字段 | 字段类型 | 字段说明 |
|---|---|---|
| phone | int | 手机号 |
| password | string | 密码 |
1.4 返回结果
{
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vc2FsZS1hcGkuZGV2L2xvZ2luIiwiaWF0IjoxNDkxNTMyOTI4LCJleHAiOjE0OTIyNTI5MjgsIm5iZiI6MTQ5MTUzMjkyOCwianRpIjoiN1hCUXdwN1FHZmxUdHVVQiIsInV1aWQiOiI1MDZjYWY3MCJ9.FyyXagHtBfDBtMJZPV_hm2q6CVULpY63JPDGDHXc"
},
"code": "200",
"msg": "SUCCESS"
}
1.5 返回参数
| 字段 | 字段类型 | 字段说明 |
|---|---|---|
| token | string | token值 |
1.6 错误状态码
| 状态码 | 说明 |
|---|---|
| 3001 | 其他认证错误信息！ |
| 3002 | 用户不存在！ |
| 3003 | 用户名或密码有误！ |
部分代码如下：
## 1. 登录
### 1.1 功能描述
提供手机号和密码的登录方式。
### 1.2 请求说明
> 请求方式：POST<br>
请求URL ：[login](#)
### 1.3 请求参数
字段 |字段类型 |字段说明
------------|-----------|-----------
phone |int |手机号
password |string |密码
### 1.4 返回结果
```json
{
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vc2FsZS1hcGkuZGV2L2xvZ2luIiwiaWF0IjoxNDkxNTMyOTI4LCJleHAiOjE0OTIyNTI5MjgsIm5iZiI6MTQ5MTUzMjkyOCwianRpIjoiN1hCUXdwN1FHZmxUdHVVQiIsInV1aWQiOiI1MDZjYWY3MCJ9.FyyXagHtBfDBtMJZPV_hm2q6CVULpY63JPDGDHXc"
},
"code": "200",
"msg": "SUCCESS"
}
### 1.5 返回参数
字段 |字段类型 |字段说明
------------|-----------|-----------
token |string |token值
### 1.6 错误状态码
状态码 |说明
------------|-----------
3001 |其他认证错误信息！
3002 |用户不存在！
3003 |用户名或密码有误！
更多的源码内容，请查看api-doc
网友评论