从 Rap 迁移至 ShowDoc 的文档编写设计,支持多级参数
1、在 Rap 上编写接口文档,可以使用 导入 JSON 的功能,且支持多级参数。如图1
2、在 ShowDoc 上编写接口文档,没有提供 导入 JSON 的功能,必须手动基于 Markdown 编写。如图2
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | **简要描述:** - 用户注册接口 **请求URL:** **请求方式:** - 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
4、参考 京东 的接口文档在多级参数上的实现。每一级参数占用一列。不过其合并单元格的实现存在一定的难度。不准备在 ShowDoc 上实现。如图4
5、准备自行制作一份模板:互动运营 API 接口模板,让其支持多级参数。以后需要新建一份文档时,插入此模板就是。如图5
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | **接口名称:** - 创建任务组 ( 即一键多渠道发布 ) **请求 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": [ ], "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": [ ], "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
近期评论