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

× 请我吃糖~
打赏二维码