接口的参数之间的互相依赖要怎么表达在文档里？

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

V2EX 提问指南

这是一个创建于 853 天前的主题，其中的信息可能已经有所发展或是发生改变。

比如一个接口的参数 B 当且仅当参数 A 提供了的时候必须提供，而参数 A 本身是可选参数。
又比如一个接口的参数 A 、B 必须要提供其中之一或者同时提供，但不能同时省略。

参数

接口

提供

省略

9 条回复 • 2022-07-25 17:30:13 +08:00

zhazi

2022-07-25 13:55:40 +08:00

文档里？
文档不是想怎么写怎么写
你要说接口里可以看下 restful level3

yunying

2022-07-25 14:24:47 +08:00

感觉应该要合并成一个接口来控制比较妥当。。要不分开了的话。你还是很难保证调用方会不会随心所欲地使用

wu67

2022-07-25 14:40:05 +08:00

params: { a: { value: balabala, b: 11111 } }.

params: [a, b, ...]

kera0a

2022-07-25 14:45:54 +08:00

重载呗，
伪代码写一下类似下面这样

第一种
func (any? A = a)
func (any A, any A)

第二种
func (any A, any B)
func (any A)
func (any B)

micean

2022-07-25 14:55:52 +08:00

文档的话，字段说明里写一下不就行了吗？

damai0419

2022-07-25 15:43:44 +08:00

一般写字段备注里。
1. B：仅当 A 有值时，此字段有值。
2. A: A 、B 不可同时为空。
B: A 、B 不可同时为空。

wolfie

2022-07-25 15:45:29 +08:00

必填列写明二选一必填。

Jooooooooo

2022-07-25 15:56:18 +08:00

加个备注项.

RainyH2O

2022-07-25 17:30:13 +08:00

@damai0419 看来是只有备注了。其实像 JSON Schema Validation 有提供 dependentRequired ，但是 OpenAPI Specification 却迟迟没提供类似功能。我想了解下大家平时怎么解决的，唯一的问题是备注这种纯文本没法借助 Validator 工具做自动化结构校验。