Question

我有一个API，我将一组对象发布到服务器，按类型区分，其中每种类型都有一些不同的参数。这些命令的结构如下：

{
    "type": <command-name>,
    "args": { 
        <command-specific args>
    }
}

例如，这些可能是两个可能的命令：

{
    "type": "Flooblinate",
    "args": {
        "intensity": "High",
        "frequency": "Every blue moon"
    }
}

{
    "type": "Blagostrate",
    "args": {
        "temperature": 34.5,
        "darkMatter": true
    }
}

如何在Swagger中指定？我可以为enum指定"type"，但我怎么说“"args"是这些可能的对象之一”？

我已经查看the docs，但没有什么突出的。最有希望的是allOf因为它在编辑器中显示得很好（pastebin，粘贴到online editor）：

definitions:
  Product:
    type: object
    allOf:
    - type: object
      title: Flooblinate
      properties:
        intensity:
          type: string
        frequency:
          type: string

    - type: object
      title: Blagostrate
      properties:
        temperature:
          type: number
        darkMatter:
          type: boolean

看起来像这样：

然而，这在语义上并不是我所需要的，并且，毫不奇怪，在online viewer（我没有为我的测试用例设置，不确定如何轻松链接本地文件），表示好像所有字段同时出现，这当然是allOf的含义：

用Swagger表示这个的正确方法是什么？

Answer 1

根据Ron对the google group的意见，我想要的是使用discriminator属性：

definitions:
  Product:
    type: object
    discriminator: type
    properties:
      type: string
    required: [type]
  Flooblinate:
    allOf:
    - $ref: '#/definitions/Product'
    - type: object
      properties:
        intensity:
          type: string
        frequency:
          type: string
  Blagostrate:
    allOf:
    - $ref: '#/definitions/Product'
    - type: object
      properties:
        temperature:
          type: number
        darkMatter:
          type: boolean

从语义上讲，这意味着我想要的意思。我应该在API接受的地方指定$ref: '#/definitions/Product'，或者返回Flooblinate或Blagostrate中的任何一个。请注意，这需要在对象上使用一个字段（此处称为type）作为鉴别器。

我认为这可能是方法，但工具没有显示我的预期。但是：

那是因为工具不是100％支持鉴别器 - 但是，这是描述用例的正确方法。一旦你在顶级模型中定义了鉴别器，任何'allOf'都会被认为是一个可行的选择，实际上你会参考最高级别的模型来使用。

如何指定对象的类型是几种可能的对象类型之一？

1 个答案: