Api文档的编辑

Api文档的编辑

在用markdown编辑api文档的时候，可以自动生成目录。用git做版本管理，然后用工具Typora（可以直接到typora官网下载）来查看

  1 [TOC]  
  2 # XXX项目api文档
  3 ## 接口说明：
  4 ### 一. 组织管理
  5 #### 1. 组织架构相关
  6 ##### 1.1 组织架构人员同步
  7 >获取政务微信组织架构
  8 >请求参数：
  9 
 10 | 参数名       | 说明           | 参数类型    | 是否必须 | 缺省值|
 11 | ------------| ---------------| -----------| --------| ---- |
 12 | token         | token |  string |是  |     | 
 13 
 14 请求实例：
 15    GET/POST
 16    [v1/test/sync]()
 17    HTTP/1.1 Host: [https://test.XXX.com/api/]
 18 
 19 返回结果：
 20 ```json
 21 {
 22     "code": 0,
 23     "data": [],
 24     "msg": "已发送到同步队列，请稍后查看结果"
 25 }
 26 ```
 27 
 28 返回参数：
 29 
 30 
 31 | 参数名       | 含义                  | 参数类型   | 长度 |
 32 | ------------ | ---------------------| ---------- | ---- |
 33 |msg           |提示信息              | string    |  -   |
 34 
 35 ##### 1.2 组织架构人员列表
 36 
 37 接口说明：
 38 >人员列表
 39 >请求参数：
 40 
 41 | 参数名       | 说明           | 参数类型    | 是否必须 | 缺省值|
 42 | ------------| ---------------| -----------| --------| ---- |
 43 | token         | token| string  | 是  |     |
 44 | limit         | 每页条数| integer  | 是  |     |
 45 | page         | 页码| integer  | 是  |     |
 46 | position      | 职位| string  | 否  |   无  |
 47 
 48 请求实例：
 49    GET/POST
 50    [v1/test/user_list]()
 51    HTTP/1.1 Host: [https://test.XXX.com/api/]
 52 
 53 返回结果：
 54 获取列表成功
 55 
 56 ```json
 57 {
 58     "code": 0,
 59     "data": {
 60         "current_page": 1,
 61         "total_page": 1,
 62         "total_count": 1
 63     },
 64     "msg": "获取成功！"
 65 }
 66 ```
 67 返回参数：
 68 
 69 | 参数名      | 含义                | 参数类型   | 长度 |
 70 | ----------- | --------------------| ------ | ---- |
 71 |cusTags      | 标签   | array  | -   |
 72 |current_page      | 当前页|  integer  |
 73 |total_page      | 总页数|  integer  |
 74 |total_count      | 总条数|  integer  |
 75 
 76 
 77 
 78 #### 2. 工作小组
 79 ##### 2.1导入工作小组
 80 
 81 >导入工作小组
 82 >请求参数：
 83 
 84 | 参数名       | 说明           | 参数类型    | 是否必须 | 缺省值|
 85 | ------------| ---------------| -----------| --------| ---- |
 86 | token         | token |  string |是  |   是  | 
 87 | activityid      | 活动id   | string  | 是   |
 88 
 89 请求实例：
 90    GET/POST
 91    [v1/test/import_work_group]()
 92    HTTP/1.1 Host: [https://test.XXX.com/api/]
 93 
 94 返回结果：
 95 ```json
 96 {
 97     "code": 0,
 98     "data": [],
 99     "msg": "导入成功"
100 }
101 ```
102 
103 返回参数：
104 
105 
106 | 参数名       | 含义                  | 参数类型   | 长度 |
107 | ------------ | ---------------------| ---------- | ---- |
108 |msg           |提示信息              | string    |  -   |
109 
110 
111 
112 ### 二.  通知消息
113 #### 1. 巡检任务通知消息
114 >巡检任务通知消息
115 >请求参数：
116 
117 | 参数名       | 说明           | 参数类型    | 是否必须 | 缺省值|
118 | ------------| ---------------| -----------| --------| ---- |
119 | token       | header中的token |  string |是  |   无  | 
120 | activityid  | header中的activityid  |  string |是  |   无  | 
121 
122 请求实例：
123    GET/POST
124    [v1/test/inspection]()
125    HTTP/1.1 Host: [https://test.XXX.com/api/]
126 
127 返回结果：
128 通知消息发送成功
129 ```json
130 {
131     "code": 0,
132     "data": [],
133     "msg": ""
134 }
135 ```

 

说明：上面的 [TOC] 代表会自动生成目录

在typora上面查看：

 

posted @ 2020-10-09 19:11  欢乐豆123  阅读(391)  评论(0)  编辑  收藏  举报