V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
RainyH2O
V2EX  ›  问与答

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

  •  
  •   RainyH2O · 2022-07-25 13:30:58 +08:00 · 1322 次点击
    这是一个创建于 871 天前的主题,其中的信息可能已经有所发展或是发生改变。
    比如一个接口的参数 B 当且仅当参数 A 提供了的时候必须提供,而参数 A 本身是可选参数。
    又比如一个接口的参数 A 、B 必须要提供其中之一或者同时提供,但不能同时省略。
    9 条回复    2022-07-25 17:30:13 +08:00
    zhazi
        1
    zhazi  
       2022-07-25 13:55:40 +08:00
    文档里?
    文档不是想怎么写怎么写
    你要说接口里可以看下 restful level3
    yunying
        2
    yunying  
       2022-07-25 14:24:47 +08:00
    感觉应该要合并成一个接口来控制比较妥当。。要不分开了的话。你还是很难保证调用方会不会随心所欲地使用
    wu67
        3
    wu67  
       2022-07-25 14:40:05 +08:00
    params: { a: { value: balabala, b: 11111 } }.

    params: [a, b, ...]
    kera0a
        4
    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
        5
    micean  
       2022-07-25 14:55:52 +08:00
    文档的话,字段说明里写一下不就行了吗?
    damai0419
        6
    damai0419  
       2022-07-25 15:43:44 +08:00
    一般写字段备注里。
    1. B:仅当 A 有值时,此字段有值。
    2. A: A 、B 不可同时为空。
    B: A 、B 不可同时为空。
    wolfie
        7
    wolfie  
       2022-07-25 15:45:29 +08:00
    必填列 写明 二选一 必填。
    Jooooooooo
        8
    Jooooooooo  
       2022-07-25 15:56:18 +08:00
    加个备注项.
    RainyH2O
        9
    RainyH2O  
    OP
       2022-07-25 17:30:13 +08:00
    @damai0419 看来是只有备注了。其实像 JSON Schema Validation 有提供 dependentRequired ,但是 OpenAPI Specification 却迟迟没提供类似功能。我想了解下大家平时怎么解决的,唯一的问题是备注这种纯文本没法借助 Validator 工具做自动化结构校验。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   894 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 23ms · UTC 20:54 · PVG 04:54 · LAX 12:54 · JFK 15:54
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.