rest - HTTP POST 请求正文中的备用字段

Question

我一直在寻找为具有两个互斥字段的 HTTP POST 请求指定正文类型的最佳方法。我正在为 API 规范使用 swagger，并且我有一个请求必须具有 field_A 或 field_B，但不能同时具有两者。

现在我将两个字段都设置为可选，在规范中描述行为(何时设置一个字段或另一个字段)，并验证服务器上的输入。如果没有填写任何字段，我将返回 400-Bad-request。

我的问题是这是否是正确的方法(如果我指定一个额外的内容类型会不会更符合 REST 风格？)，或者 Swagger 中是否有一些东西可以让我使这种行为更加明显。

Answer 1

我遇到了一个解决了我的问题的 API。对于给定的字段，该字段的类型是可扩展的(如基类和多个扩展类)。为了区分不同的子类型，有一个鉴别器字段。

例如(swagger 格式的 YAML)，类型 Foo 是可扩展的并且有子类型 FooA 和 FooB。鉴别器是一个类型字段:

definitions:
  Foo:
    type: object
    properties:
      type: string
      x-extensible-enum:
        - FOO_A
        - FOO_B
      discriminator: type
      required:
        - type
  FOO_A:
    allOf:
      - $ref: '#/definitions/Foo'
      - type: object
        properties:
          field_a:
            type: string
        required:
          - field_a
  FOO_B:
    allOf:
      - $ref: '#/definitions/Foo'
      - type: object
        properties:
          field_b:
            type: integer
            format: int32
        required:
          - field_b

这使得反序列化更加复杂，但这是一种非常有趣且非常灵活的方法。