REST接口文档编写规范

发表于 更新于

REST接口文档遵循 API Blueprint 编码规范

中文说明需要遵循 中文文案排版指北

按照该格式书写的文档, 可以被 GitLab 及 Gollum 完美解析

主要内容

  1. 使用 Markdown 编写
  2. 请求和响应主体, 使用8个字符缩进
  3. 不使用` 包裹json代码

Demo

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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

## 用户密码 [/users/password]

### 重置密码 [PATCH]


+ Attributes
    + phone (number, required) - 手机号码
    + password (string, required) - 密码
    + verify_code (string, required) - 短信验证码

+ Header 
    + Authorization Bearer: {clientToken} - 访问令牌, 通过客户端模式获得
    + Content-Type: application/json

+ Request (application/json)

        {
            "phone":"17083300514",
            "password":"pa66w0rd",
            "verify_code":"312338"
        }

+ Response 201 (application/json)      

        {
            "phone":"17083300514",
            "password":"pa66w0rd",
            "verify_code":"312338"
        }

+ Response 422 (application/json)

        [
          {
            "field": "verify_code",
            "message": "短信验证码错误"
          },
          {
            "field": "phone",
            "message": "手机号不存在"
          },
         {
            "field": "password",
            "message": "密码至少包含一位数字"
          }
        ]
        
        
        
## 扫描二维码 [/qrcode-tokens/{ticket}]

### 更新状态 [PUT]

+ Attributes
    + action (string, required) - 动作, 值为SCANNED或LOGGED_IN
    + ticket (string, required) - ticket 二维码中链接中后面的字符串

+ Header 
    + Authorization: Bearer {clientToken}
    + Content-Type: application/json

+ Request (application/json)

        {
            "action":"SCANNED"
        }
  
+ Response 201 (application/json)      

        {
            "action":"SCANNED"
        }


参考链接