如何在 OpenAPI YAML 中为已定义组件的数组设置 EXAMPLE 值？

Question

我在 OpenAPI 中定义了以下组件：

 Template:
      type: object
      properties:
        Callback:
          description: 'If set, this url will be called with a POST when a job completes. If the text "{guid}" is in the url, that text will be replaced with the Guid for the callback.'
          type: string
        OutputFormat:
          type: string
          description: 'Generate the document in the provided format.'
          enum: [pdf, docx, xlsx, pptx, txt, html, prn, csv, rtf, jpg, png, svg, eps, bmp, gif]
        Data:
          description: 'The source of the template- embedded or external. Embed template as a Base64-encoded string.'
          type: string
          format: base64
        ConnectionString:
          description: "Set this to provide the template as a connection string of the template's location."
          type: string
        Format:
          type: string
          description: 'Format of the template. Auto-determined if not provided.'
          enum: [docx, html, xlsx, pptx]
        Properties:
          description: "Windward properties for this document. These override any properties set in the configuration file on the server side."
          type: array
          items:
            $ref: '#/components/schemas/Property' 
          xml: 
            wrapped: true 
        Parameters:
          description: "A set of input parameters for this document. The parameters are global and shared among all data sources."
          type: array
          items:
            $ref: '#/components/schemas/Parameter'
          xml: 
            wrapped: true 
        Datasources:
          description: "The datasources to apply to the template. The datasources are applied simultaneously."
          type: array
          items:
            $ref: '#/components/schemas/Datasource'
          xml: 
            wrapped: true 
        Tag:
          type: string 
          description: "Anything you want. This is passed in to the repository & job handlers and is set in the final generated document object. The RESTful engine ignores this setting, it is for the caller's use."
        TrackImports:
          type: boolean
          description: "Return all imports with the generated document."
        TrackErrors:
          type: integer
          minimum: 0
          maximum: 3
          description: "Enable or disable the error handling and verify functionality."
        MainPrinter:
          type: string
          description: "If you are using printer output use to specify main printer. Printer must be recognized by Network"
        FirstPagePrinter:
          type: string
          description: "Set first page printer if main printer is already set"
        PrinterJobName:
          type: string
          description: "Assign print job name"
        PrintCopies:
          type: integer
          description: "Set number of copies to print"
        PrintDuplex:
          type: string
          description: "Selects the printer duplex mode.  Only if supported by the printer."

如果您查看 Datasources 条目，它是 Datasource 个组件的数组：

Datasources:
   description: "The datasources to apply to the template. The datasources are applied 
   simultaneously."
          
   type: array
   items:
     $ref: '#/components/schemas/Datasource'

我正在尝试为 POST 请求定义一个示例请求正文（您发送的正文是我上面显示的模板组件）。当我尝试定义示例值时，它看起来像这样：

这就是它呈现的内容：

问题是它将它显示为字典的字典（带有“{}”括号）。我需要它是一个字典数组（外面有“[]”）。有人知道怎么做吗？

我试过这样做：

但 Swagger Editor 不喜欢那样。有什么想法吗？

为了更清楚，这就是我想要做的：

# I NEED THIS
Datasources: [
  Datasource: {
    Name: "...",
    Type: "..."
  }
]

# INSTEAD OF THIS
Datasources: {
  Datasource: {
    Name: "...",
    Type: "..."
  }
}

Answer 1

以下是如何在 YAML 中编写对象数组（序列）。请注意每个数组项前的破折号。

example:
  ...
  Datasources:
    - Name:
      Type: json
      ConnectionString: some value
    - Name: Name2
      Type: yaml
      ConnectionString: some other value
  ...

也可以使用JSON数组语法[ ... ]，但此时数组必须写成有效JSON，即数组项必须以逗号分隔，嵌套对象必须写成 { ... }，所有键名和字符串值都用引号括起来，依此类推。

example:
  ...
  Datasources: [
    {
      "Name": null,
      "Type": "json",
      "ConnectionString": "some value"
    },
    {
      "Name": "Name2",
      "Type": "yaml",
      "ConnectionString": "some other value"
    }
  ]
  Tag: ...

如何在 OpenAPI YAML 中为已定义组件的数组设置 EXAMPLE 值？

How to set EXAMPLE value for array of a defined component in OpenAPI YAML?

yaml

swagger

openapi