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
原创文章，作者：ItWorker，如若转载，请注明出处：https://blog.ytso.com/251094.html