用Markdown写API文档

举例: 一个GET方法,用于获取验证码的接口: 在postman中已经调试完毕:

然后去(推荐)有道云笔记中编写markdown:

# API接口

## 注册

### 获取验证码

目前有4种短信验证码,对应的type是:
- 注册短信验证码: register
- 修改密码短信验证码: changePassword
- 修改手机短信验证码: changePhoneNumber
- 验证手机号短信验证码: verifyPhoneNumber
#### Request
- Method: **GET**
- URL:  ```/v1.0/open/smscode?type={type}&phone={phone}```
    - register for new user:  ```/v1.0/open/smscode?type=register&phone=13811119999```
    - forgot password: ```/v1.0/open/smscode?type=changePassword&phone=13822224444```
- Headers:
- Body:
```
```

#### Response
- Body
```
{
  "code": 200,
  "data": "730781",
  "message": "OK"
}
```

注意:为了防止短信验证码被滥用,短信如果发送后,需要隔60s才能重新发送。

对应的效果:

另外,再举个有request也有response的POST的例子:

### 创建新用户
#### Reuqest

- Method: **POST**
- URL: ```/v1.0/open/register```
- Headers: Content-Type:application/json
- Body:
```
{
    "phone" : "13511112222",
    "smsCode" : "730781",
    "email" : "[email protected]",
    "firstName" : "crifan",
    "lastName" : "Li",
    "password" : "654321",
    "facebookUserId" : "123907074803456"
}
```

#### Response
- Body
```
{
  "code": 200,
  "data": {
    "avatarUrl": "",
    "createdAt": "2016-10-24T20:39:46",
    "curRole": "IdleNoRole",
    "email": "[email protected]",
    "errandorRating": 0,
    "facebookUserId": "123907074803456",
    "firstName": "crifan",
    "id": "user-4d51faba-97ff-4adf-b256-40d7c9c68103",
    "isOnline": false,
    "lastName": "Li",
    "location": {
      "createdAt": null,
      "fullStr": null,
      "id": null,
      "latitude": null,
      "longitude": null,
      "shortStr": null,
      "updatedAt": null
    },
    "locationId": null,
    "password": "654321",
    "phone": "13511112222",
    "shareCodeCount": 0,
    "updatedAt": "2016-10-24T20:39:46"
  },
  "message": "new user has created"
}
```

markdown生成文档的效果:

所以后续其他接口,均可参考上面的GET/POST等接口的写法,去写出对应的markdown的源文件,生成API文档后,效果还是不错的。

当然,也可以用其他Markdown编辑器去写md文件,去生成对应API文档。

另外,再附上,在写具体单个API接口之前的声明的部分:

# 文档说明
## 服务器API地址
前缀:
```http://115.29.173.126:21084/runningfast/api```


完整的API地址为:```前缀```+```具体接口路径```

比如,获取验证码都接口为:
```http://115.29.173.126:21084/runningfast/api``` + ```/v1.0/open/smscode```

->

```http://115.29.173.126:21084/runningfast/api/v1.0/open/smscode```

## 调用接口说明
- 如果参数格式是==JSON==的话:提交request请求时必须添加header头:==Content-Type:application/json==
- 请求中是否要包含头信息:==Authorization:{accesstoken}==
    - 接口中==包含==```/open/```的:不需要添加
    - 接口中==不包含==```/open/```:需要添加
        - 说明该接口都需要对应的权限才可以访问,所以需要在请求中包含头信息:```Authorization:{accesstoken}```
    - 当access token无效或者已过期时,返回:
```
{
  "code": 401,
  "message": "invalid access token: wrong or expired"
}
```

- 所有的接口的返回形式都是统一为:
    - 正常返回
```
{
  "code": 200,
  "message": "OK",
  "data": 某种类型的数据,比如字符串,数字,字典等等
}
```
    - 错误返回

```
{
  "code": 具体的错误码,
  "message": "具体的错误信息字符串"
}
```

文档效果:

  • 优点:简单易上手
  • 缺点:后续API更新后,需要及时更新markdown的文档内容

results matching ""

    No results matching ""