后端接口功能开发完成后，接入接口的同事需要知道每个接口的功能，以及请求需要带哪些参数等，所以，提供接口文档给别人查看就显得非常必要了；用Markdown写文档的好处在于文档的排版整齐、格式统一，写起文档更加简单、快速。关于 Markdown 的详细语法，可以参考Markdown 语法说明。
  最近在 github 上开源了基于Markdown编写的接口文档项目api-doc，供大家参考使用；生成的文档如下图：

markdown-api

下面大概讲解文档的相关内容：

一、环境部署/安装

文档基于 gitbook 运行的，所以需要配置 gitbook 的运行环境，配置过程如下：

1.1 克隆源代码

1
git clone https://github.com/WongMinHo/api-doc.git

1.2 配置本地运行环境

1.2.1 安装npm
从官网下载源码，解压，执行如下命令安装：

1
2
3
./configure
make
make install

1.2.2 安装gitbook

1
npm install gitbook-cli -g

如果安装太慢，可以设置淘宝代理镜像，执行命令：

1
npm config set registry https://registry.npm.taobao.or

查看gitbook是否安装成功：

1
gitbook -V

1.2.3 使用
进入api-doc目录，执行命令：

1
gitbook serve

浏览器打开：http://localhost:4000/
即可访问文档。

二、文档使用说明

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 格式返回；接口返回一共有三种情况：
1) 操作成功后返回，范例：

1
2
3
4
{
  "code": "200",//状态码
  "msg": "SUCCESS"//信息
}

2) 成功返回数据，范例：

1
2
3
4
5
6
7
8
{
  "data": {//数据
    "name": "minhow",
    "age": "18"
  },
  "code": "200",//状态码
  "msg": "SUCCESS"//信息
}

3) 错误返回，范例：

1
2
3
4
{
  "err_code": "1001",//错误状态码
  "err_msg": "认证失败，请重新登录！"//错误信息
}

2.3.4 全局响应状态码说明
状态码 说明
200 操作成功
1001 认证失败，请重新登录！
1002 参数不合法！

三、目录

文档的接口目录结构，文档中举了三个案例，如下：
1.1 认证管理
 1.1.1 登录
 1.1.2 刷新Token值
1.2 用户管理
 1.2.1 个人中心

四、 接口说明

登录案例如下：

4.1 登录

4.1.1 功能描述

提供手机号和密码的登录方式。

4.1.2 请求说明

请求方式：POST

请求URL ：login

4.1.3 请求参数
字段 字段类型 字段说明
phone int 手机号
password string 密码
4.1.4 返回结果
1
2
3
4
5
6
7
{
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vc2FsZS1hcGkuZGV2L2xvZ2luIiwiaWF0IjoxNDkxNTMyOTI4LCJleHAiOjE0OTIyNTI5MjgsIm5iZiI6MTQ5MTUzMjkyOCwianRpIjoiN1hCUXdwN1FHZmxUdHVVQiIsInV1aWQiOiI1MDZjYWY3MCJ9.FyyXagHtBfDBtMJZPV_hm2q6CVULpY63JPDGDHXc"
  },
  "code": "200",
  "msg": "SUCCESS"
}
4.1.5 返回参数
字段 字段类型 字段说明
token string token值
4.1.6 错误状态码
状态码 说明
3001 其他认证错误信息！
3002 用户不存在！
3003 用户名或密码有误！

部分代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
## 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

最后更新： 2018年01月14日 10:40

原始链接： http://blog.minhow.com/articles/openproject/markdown-write-api/

赏
× 请我吃糖~
打赏二维码