为带有可选字段的swagger.yaml对象提供“示例值”

Question

我试图在'Model'选项卡中提供更多描述，并在'Example Value'选项卡中为带有可选对象的swagger.yaml对象提供示例值

我的PATCH请求（RestAPI）使用的模型在我的swagger.yaml中定义如下：

  mymodel:
    items:  
      - $ref: '#/definitions/modelHeader'
      - $ref: '#/definitions/modelPayload'

目前mymodel有 '模型'为“mymodel {}”，'示例值'为“{}”

modelHeader和modelPayload是定义了示例的复合对象。 即使mymodel没有强制要求任何字段，我希望它用示例显示这些可选字段。

我知道我可以像example: [{name: 'myname', value: 'myvalue1'},{name: 'myname2', value: 'myvalue2'}]

那样定义一个最小的例子

但这很麻烦，仍然没有填充'模型'。 是否可以为json提供一个url作为例子？

任何提示或想法都将不胜感激。我还是YAML规范的新手

Answer 1

您的规范无效，因为items需要单一类型而不是类型数组：

items:
  type: string

# or

items:
  $ref: '#/definitions/something'

  

我希望mymodel成为使用＆＃39; allOf＆＃39;

的对象

allOf的正确语法是：

  mymodel:
    allOf:  
      - $ref: '#/definitions/modelHeader'
      - $ref: '#/definitions/modelPayload'

allOf重用每个模型中的example个。例如，如果基本模型定义如下：

  modelHeader:
    type: object
    properties:
      id:
        type: integer
        example: 1

  modelPayload:
    type: object
    properties:
      name:
        type: string
        example: Alice

mymodel得到了这个例子：

{
  "id": 1,
  "name": "Alice"
}