这是一个创建于 844 天前的主题，其中的信息可能已经有所发展或是发生改变。
之前内部前后端文档都是用 swagger 、yapi 之类的。现在要给一些对外的接口文档，但是是通过 PDF 的形式给出而不是提供一个 Web 平台，而且这个 PDF 内容的结构和格式都要求比较严格，所以都是先写一份 word ，再转成 PDF 。如果遇到参数是 object 的结构，参数表格里面要体现这种嵌套层级的关系感觉就比较麻烦了，缩进、合并单元格之类的领导都觉得不太美观，所以就比较犯难，不知道各位有没有比较好的例子和建议可供参考
 |
1
Jooooooooo 2022-07-19 15:40:54 +08:00
合并单元格都不美观还要啥...
直接一个大 json? |
 |
2
murmur 2022-07-19 15:43:46 +08:00
List<Next 嵌套的 Object>，Next 嵌套的 Object 单独在出一节文档，以此类推，每次嵌套都定义一各新对象
|
|
3
murmur 2022-07-19 15:44:57 +08:00
比如 Form 、FormField 、FormFieldOptions 这样
|
 |
4
MoYi123 2022-07-19 15:45:47 +08:00
抄阿里云的接口文档格式就行了, 领导觉得有问题就让他看阿里云是怎么做的.
|
 |
5
zydxn 2022-07-19 15:45:51 +08:00
习惯用 markdown 写，再转 PDF ，markdown 里面贴 JSON 不乱
|
 |
6
lower 2022-07-19 15:48:18 +08:00
object 参数的说明，备注详情请参考下文 xxx ，或者附录 xxx ，直接底下新起一段说明和 object 内部参数表格说明；
最后，在展示一个完整示例 json |
 |
7
Elietio OP 
我也参考了市面上的一些例子，做了三个样式，但是领导觉得都不行。。。 |
 |
11
FYFX 2022-07-19 16:23:33 +08:00
我以前写法就是每个对象都是一个表格，然后就一堆小表格
|
 |
12
chavyleung 2022-07-19 16:30:29 +08:00
如 #6 说的，腾讯 serverless 就是这么干的
https://github.com/serverless-components/tencent-http/blob/master/docs/configure.md |
 |
13
Chad0000 2022-07-19 16:35:48 +08:00
面向领导编程，惨，无语。
|
 |
14
fgwmlhdkkkw 2022-07-19 17:03:12 +08:00
图片怎么样……
|
 |
15
storyxc 2022-07-19 19:17:44 +08:00
还好我领导没这么多屁事😅
|
 |
16
unco020511 2022-07-19 20:05:19 +08:00
每个 object 节点是一个表格
|
 |
17
akira 2022-07-19 21:06:27 +08:00
需要嵌套的地方 单独拎出来写
|
 |
18
grissom 2022-07-19 21:08:53 +08:00
领导提的让领导出模板
|
 |
19
Jinnyu 2022-07-20 09:31:58 +08:00
| 参数名称 | 参数类型 | 参数说明 | 备注 |
| :--------------- | :--------- | :----------- | :-------------------------------------------------------- | | code | String | 接口响应码 | 完整响应码见[附录 1](#附录 1-短信服务状态码) | | msg | String | 接口响应信息 | 接口返回信息, 可通过本字段排查问题. | | data | JSONObject | 接口响应数据 | | | data\.sequenceId | String | 流水号 | 短信服务业务流水号(22 位)<br>后续可根据流水号查询发送状态. | |
 |
20
siweipancc 2022-07-20 13:48:08 +08:00 via iPhone
嵌套的应该是 obj ，锚点到另一张表
|
Select Language