api 文档规范制定
引言
api文档一直诟病,文档不齐除外,主要是规范不统一,百花齐放。现在重新制定api新的规范。
模板
目录:
- 简要描述
- 请求url
- 请求方式
- 请求参数
- 请求参数说明
- 返回示例
- 返回参数说明
- 备注
示例
因为一直使用mediawiki,示例备注
= API/V2/Achievement.getTaskList = == 简要描述 == 获取成就任务列表 == 请求URL == http://xxxx == 请求方式 == POST == 请求参数 == { "mid":"33", "protocol":1, "api":"33", "sig":"xx", "vkey":"xx", "time":1497414550, "sid":305, "langtype":1, "username":"听说123", "version":"7.9.121", "mtkey":"xx", "unid":"488", "method":"Achievement.getTaskList", "vmid":"501644", "param":{ "type":1 }, "_unset":[ "_unset", "mbsid" ], "mbsid":"488" } == 请求参数说明 == {| class="wikitable" |- ! 参数名 !! 必选 !! 类型 !! 说明 |- | type || 是 || int || 请补充说明 |} == 返回示例 == { "sys":[ 17051110, 0 ], "time":1497414550, "ret":{ "cdnVer":"", "picPath":"xx", "list":[ { "taskId":1, "conditionNum":2, "chips":0, "status":1, "new":null, "levels":"", "name":"xxx", "desc":"xxx", "progress":0 } ], "allCnt":52, "completeCnt":0, "finishCnt":null }, "api":"v5", "flag":1 } == 返回参数说明 == {| class="wikitable" |- ! 参数名 !! 类型 !! 说明 |- | taskId || int || 补充说明 |} == 备注 == 描述备注
视图
- Author: josephzeng
- License: CC BY-NC-ND 4.0