从 Rap 迁移至 ShowDoc 的文档编写设计，支持多级参数

1、在 Rap 上编写接口文档，可以使用 导入 JSON 的功能，且支持多级参数。如图1

图1

2、在 ShowDoc 上编写接口文档，没有提供 导入 JSON 的功能，必须手动基于 Markdown 编写。如图2

图2

 
    
**简要描述：** 

- 用户注册接口

**请求URL：** 
- ` http://xx.com/api/user/register `
  
**请求方式：**
- POST 

**参数：** 

|参数名|必选|类型|说明|
|:----    |:---|:----- |-----   |
|username |是  |string |用户名   |
|password |是  |string | 密码    |
|name     |否  |string | 昵称    |

 **返回示例**

``` 
  {
    "error_code": 0,
    "data": {
      "uid": "1",
      "username": "12154545",
      "name": "吴系挂",
      "groupid": 2 ,
      "reg_time": "1436864169",
      "last_login_time": "0",
    }
  }
```

 **返回参数说明** 

|参数名|类型|说明|
|:-----  |:-----|-----                           |
|groupid |int   |用户组id，1：超级管理员；2：普通用户  |

 **备注** 

- 更多返回错误代码请看首页的错误代码描述


欢迎使用ShowDoc！

3、在 ShowDoc 上编写接口文档，其默认模板仅支持一级参数。查看模板文档的最终显示效果。如图3

图3

4、参考 京东 的接口文档在多级参数上的实现。每一级参数占用一列。不过其合并单元格的实现存在一定的难度。不准备在 ShowDoc 上实现。如图4

图4

5、准备自行制作一份模板：互动运营 API 接口模板，让其支持多级参数。以后需要新建一份文档时，插入此模板就是。如图5

图5

    
**接口名称：** 

- 创建任务组 ( 即一键多渠道发布 )

**请求 URL：** 
- ` /v1/task-groups/standard `
  
**请求类型：**
- POST 

**请求参数：** 

|参数|二级参数|必填|类型|说明|
|:----    |:----    |:---|:----- |-----   |
|task_group | |是  |object |任务组   |
| |source |是  |string |来源   |
| |source_article_id |是  |int |任务组的来源文章ID   |
| |source_callback_url |是  |string |来源回调地址   |
| |source_pub_user_id |是  |int |来源发布用户ID   |
| |source_uuid |是  |string |来源ID(UUID)   |
|qq | |否  |array<object> |企鹅号，默认：null   |
| |article_category_id |是  |int |文章分类ID   |
| |author |否  |string |作者，默认：空字符串   |
| |channel_app_source_uuids |是  |array<string> |渠道的应用的来源ID(UUID)   |
| |content |是  |string |内容   |
| |cover_type |否  |int |封面类型，1：单图；3：三图，默认：1   |
| |covers |是  |array<string> |封面图，其数量必须与 cover_type 的值相等。分辨率需要大于等于 360 * 270。不支持 GIF。   |
| |original |否  |int |是否申请原创文章，0：否；1：是(需要用户具有发表图文原创文章资格否则无效)，默认：0   |
| |original_author |否  |string |原创首发作者，申请原创文章时当选择平台不是企鹅号时必填，默认：空字符串   |
| |original_platform |否  |int |原创首发平台，0：空；1：企鹅号；2：微信公众账号；3：头条号；4：大鱼号；5：一点号；6：百家号；7：网易号；8：搜狐号；9 ：淘宝头条；10：其它平台。申请原创文章时必填，默认：0   |
| |original_url |否  |string |原创首发链接，申请原创文章时当选择平台不是企鹅号时必填，默认：空字符串   |
| |source_article_id |是  |int |来源文章ID   |
| |tag |否  |string |文章标签，以英文半角逗号分隔，最长不能超过 60 个字符，默认：空字符串    |
| |title |是  |string |标题，6 - 35 个字符    |

 **请求示例**

``` 
{
    "task_group": {
        "source": "spider",
        "source_uuid": "825e6d5e36468cc4bf536799ce3565cf",
        "source_pub_user_id": 1,
        "source_callback_url": "http://scms.wjdev.chinamcloud.cn/api/thirdPush/callBack",
        "source_article_id": 1
    },
    "qq": [
        {
            "channel_app_source_uuids": [
                "36cf694a67fc11eaa79d54ee75d2ebc1"
            ],
            "title": "北京小汤山医院启用，设千张床位",
            "content": "3月16日晚拍摄的北京小汤山医院局部（无人机照片）。记者从北京市疫情防控领导小组获悉，为做好境外输入人员疫情防控工作，3月16日起，启用北京小汤山医院。医院设床位1000余张，将主要用于境外来（返）京人员中需筛查人员、疑似病例及轻型、普通型确诊患者的筛查和治疗。",
            "source_article_id": 4,
            "author": "鞠焕宗",
            "article_category_id": 24,
            "tag": "北京,疫情,防控,境外,输入,小汤山,医院",
            "covers": [
                "http://pic-bucket.ws.126.net/photo/0001/2020-03-17/F7TNMMRG00AN0001NOS.jpg",
                "http://pic-bucket.ws.126.net/photo/0001/2020-03-17/F7TNMMRH00AN0001NOS.jpg",
                "http://pic-bucket.ws.126.net/photo/0001/2020-03-17/F7TNMMRI00AN0001NOS.jpg"
            ],
            "cover_type": 3,
            "original": 0,
            "original_platform": 0,
            "original_url": "",
            "original_author": ""
        },
        {
            "channel_app_source_uuids": [
                "55f62c8c67fc11ea809554ee75d2ebc1"
            ],
            "title": "北京小汤山医院启用，设千张床位",
            "content": "3月16日晚拍摄的北京小汤山医院局部（无人机照片）。记者从北京市疫情防控领导小组获悉，为做好境外输入人员疫情防控工作，3月16日起，启用北京小汤山医院。医院设床位1000余张，将主要用于境外来（返）京人员中需筛查人员、疑似病例及轻型、普通型确诊患者的筛查和治疗。",
            "source_article_id": 5,
            "author": "鞠焕宗",
            "article_category_id": 24,
            "tag": "北京,疫情,防控,境外,输入,小汤山,医院",
            "covers": [
                "http://pic-bucket.ws.126.net/photo/0001/2020-03-17/F7TNMMRJ00AN0001NOS.jpg",
                "http://pic-bucket.ws.126.net/photo/0001/2020-03-17/F7TNMMRH00AN0001NOS.jpg",
                "http://pic-bucket.ws.126.net/photo/0001/2020-03-17/F7TNMMRI00AN0001NOS.jpg"
            ],
            "cover_type": 3,
            "original": 0,
            "original_platform": 0,
            "original_url": "",
            "original_author": ""
        }
    ]
}
```

 **响应参数** 

|参数|二级参数|类型|说明|
|:----    |:----    |:----- |-----   |
|code | |int   |返回码，10000为正确，其他为错误  |
|data | |object   |数据  |
| |group_id |string   |租户ID  |
| |source_article_id |int   |来源文章ID  |
| |is_deleted |int   |是否被删除，0：否；1：是  |
| |deleted_at |int   |删除时间  |
| |status |int   |状态，0：禁用；1：启用  |
| |created_at |int   |创建时间  |
| |updated_at |int   |更新时间  |
| |uuid |string   |ID(UUID)  |
| |id |int   |ID  |
|message | |string   |说明  |

 **响应示例**

``` 
{
    "code": 10000,
    "message": "已发布文章至渠道发布，待发布至多渠道，请稍候",
    "data": {
        "group_id": "015ce30b116ce86058fa6ab4fea4ac63",
        "source_article_id": 1,
        "is_deleted": 0,
        "deleted_at": 0,
        "status": 1,
        "created_at": 1584943900,
        "updated_at": 1584943900,
        "uuid": "29952b546ccd11eaa21c54ee75d2ebc1",
        "id": 5
    }
}
```

 **备注** 
 字符长度的计算，如未特别说明，英文与中文皆计算为 1 个长度。

6、查看模板：互动运营 API 接口模板的最终显示效果。符合预期。如图6

图6