使用http://rap2.taobao.org/写测试接口文档

下面以设计评论接口为例，简单说明接口文档应该如何撰写。

首先，我们可以定义全局返回状态码。

返回码	返回信息	说明
10000	获取评论成功
10001	创建评论成功
10002	⽆无法创建评论	创建评论时因违反审核机制⽽而⽆无法创建
10003	评论已被删除	查看评论时评论因不不和谐因素已被删除

1. 获取文章评论。

   GET /articles/{article-id}/comments/
   开发者:王勤勤
   最后更新时间:2018年年8月10⽇
   标签:v 1.0
   接⼝说明:获取指定文章的所有评论

   使用帮助:默认返回20条数据，需要在请求头中设置身份标识(key)

   请求参数:

   参数名	类型	是否必填	参数位置	说明
   page	整数	否	查询参数	⻚页码，默认值1
   size	整数	否	查询参数	每次获取评论数量量(10~100)，默认值20
   key	字符串	是	请求头	用户的身份标识

   响应信息：

   {
     "code": "10000",
     "message": "获取评论成功",
     "page": 1,
     "size": 20,
     "totalpage": 35,
     "contents": [
       {
         "userId": "375188",
         "userName": "刘益",
         "pubData": "2018年8月2日",
         "content": "楼上说的对"
       },
       {
         "userId": "820647",
         "userName": "刘凯",
         "pubData": "2018年4月1日",
         "content": "楼上说的对"
       },
         "items": [
       1,
       true,
       "hello",
       "VQcoWC2P1Z"
     ],
     "object": {
       "foo": 1,
       "bar": "★★★★"
     },
     "placeholder": "Hdknfjx Qgqf Ccphzclv Qaiaf Erwnsdde Mqxnuukeis Wyxerxtuo"
   }
   

   点击导出

点击第一个链接下载，在postman中导入，然后就可以测试了。

在rap2设置数据返回格式

也可以在线直接看到数据样式