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

Question

I have the following component defined in 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."

If you take a look at the Datasources entry, it is an array of Datasource component:

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

I am trying to define an example request body for the POST request (the body you send is the template component I showed above). When I try to define the example values, this is what it looks like:

And this is what it renders to:

The problem is that it is showing it as a dictionary of dictionaries (with the "{}" brackets). I need it to be an array of dictionaries (with the "[]" on the outside). Does anyone know how to do this?

I tried doing this:

but Swagger Editor doesnt like that. Any ideas?

Just to make it clearer, this is what im trying to do:

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

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

Related: How to define an example request body containing an array of complex objects in Swagger, How to add multiple example values in Swagger properties — Helen
– Helen, Commented Oct 14, 2021 at 19:15

Helen · Accepted Answer · 2021-10-14 19:14:15Z

1

Here's how to write an array (sequence) of objects in YAML. Note the dash before each array item.

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

You can also use JSON array syntax [ ... ], but in this case the array must be written as valid JSON, that is, array items must be comma-separated, nested objects must be written as { ... } with all key names and string values enclosed in quotes, and so on.

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

answered Oct 14, 2021 at 19:14

Helen

99.8k17 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

zaidabuhijleh Over a year ago

Thank you! That helped a lot!

Collectives™ on Stack Overflow

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

1 Answer 1

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related