如何在 OpenAPI YAML 中為已定義組件的數組設置示例值？

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: ...