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上面查看: