17

I am using Swagger OpenAPI Specification tool. I have a string array property in one of the definitions as follows:

cities:
    type: array
    items:
      type: string
      example: "Pune"

My API produces JSON result, so Swagger UI displays the following example for the response:

{
  "cities": [
    "Pune"
  ]
}

How can I add multiple example values for the cities array? Expecting the result as:

{
  "cities": [
    "Pune",
    "Mumbai",
    "Bangaluru"
  ]
}

Tried comma-separated strings in the example key like below:

cities:
    type: array
    items:
      type: string
      example: "Pune", "Mumbai", "Bangaluru"

But the Swagger Editor shows an error, "Bad indentation".

Is there any way to specify multiple values in the example key?

Update

User Helen below has given the correct answer. I had an indentation problem hence there were nested arrays (2d arrays)

Correct way:

cities:
    type: array
    items:
      type: string
    example: 
    - Pune
    - Mumbai

My way (which was wrong)

cities:
    type: array
    items:
      type: string
      example: 
      - Pune
      - Mumbai

Look for the indentation of the example key in the above two cases which makes the difference, its YAML indentation matters.

Improve this question

3 Answers 3

Reset to default
18

To display an array example with multiple items, add the example on the array level instead of item level:

cities:
  type: array
  items:
    type: string
  example:
    - Pune
    - Mumbai
    - Bangaluru

  # or
  # example: [Pune, Mumbai, Bangaluru]

In case of array of objects, the example would look like this:

type: array
items:
  type: object
  properties:
    id:
      type: integer
    name:
      type: string
example:
  - id: 1
    name: Prashant
  - id: 2
    name: Helen
Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

the solution you have given outputs "cities": [ [ "Pune", "Mumbai" ] ] this, which is two nested arrays which I don't want I want single array holding these names as array elements not as new arrays, Thanks for response
Where do you see nested arrays? It works fine in the Swagger Editor: i.sstatic.net/uT85I.png
Hey thanks Helen indentation was the problem see updated question.
@Prashant is right, this approach is displayed as array (both Swagger Editor and Swagger UI). There is an examples option, but still not clear how to use it within components/schemas. See viralpatel.net/openapi-multiple-examples, and swagger.io/docs/specification/adding-examples.
-1

paths: /products_1: get: responses: '200': description: "XYZ" content: application/json: schema: type: array items: $ref: '#/components/schemas/pro' example: - name : "Laptop" dist : "HP LAPTOP" - name : "Mobile" dist : "Apple Mobile"

components: schemas: pro: type: object properties: prodName: type: string example: "Laptop" prodDesc: type: string example: "Produc Description"

Improve this answer

Comments

-3

For openapi version - 3.0.0+

  major:
      type: array
      items:
        type: string
        enum:
          - Accounting
          - Business Contacts
          - Economy
          - Finance
          - Graphic Design
          - International Business Administration
          - International Relations
          - Law
          - Marketing
          - others
          - Political Science
          - Statistics
Improve this answer

1 Comment

This is not what the question is about. Your answer shows an array of an enum, whereas the question is asking how to specify a multi-value array as an example value for an array schema.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.