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

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

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

图1

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

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

图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

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

图3

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

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

图4

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

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

图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

查看模板:互动运营 API 接口模板的最终显示效果。符合预期。

图6

原创文章,作者:奋斗,如若转载,请注明出处:https://blog.ytso.com/tech/webdev/181507.html

(0)
上一篇 2021年11月1日 02:08
下一篇 2021年11月1日 02:12

相关推荐

发表回复

登录后才能评论