UP | HOME

api 文档规范制定

Table of Contents

引言

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 || 补充说明  
  |}  
  == 备注 ==  
  描述备注  

视图

/static/img/11B02E83E6DADE0CAE37E82B219BBCCA.jpg /static/img/994985FE7652889B881F34FA72110F99.png

First created: 2017-06-29 20:23:04
Last updated: 2021-11-25 Thu 23:23
Power by Emacs 27.1 (Org mode 9.4)
© 2017 – 2021 by josephzeng