Markdown接口文档

后端接口功能开发完成后，接入接口的同事需要知道每个接口的功能，以及请求需要带哪些参数等，所以，提供接口文档给别人查看就显得非常必要了；用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

请求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