2

I have a nested array as a parameter in the body of my POST method:

 parameters:
 - in: body
   name: matrix
   description: blabla
   schema:
     type: array
     items:
       schema:
         type: array
         items:
           schema:
             type: double

I would like to add an example for this array to be visible in Swagger UI. I tried the following, however it doesn't seem to work - nothing is displayed as example in the body field. If I enter [[1.0, 2.0],[3.0, 4.0]] manually in the body field in Swagger UI, it works just fine.

 parameters:
 - in: body
   name: matrix
   description: blabla
   schema:
     type: array
     items:
       schema:
         type: array
         items:
           schema:
             type: double
   example: [[1.0, 2.0],[3.0, 4.0]]

Update: After implementing Helen's suggestions, here is how it looks:

Improve this question

1 Answer 1

Reset to default
3

Here's the correct version:

  parameters:
    - in: body
      name: matrix
      description: blabla
      schema:
        type: array
        items:
          type: array
          items:
            type: number
            format: double
        example: [[1.0, 2.0],[3.0, 4.0]]

List of fixes:

  • No need for schema under items.
  • type: double should be type: number + format: double (see Data Types).
  • The array example should be alongside type: array in the schema. Parameters themselves do not support the example keyword.

You can use the online Swagger Editor to check your spec for syntax errors, it will flag the lines with errors.

Note for Swagger UI 2.x

Swagger UI 2.x does not display body parameter examples if the body is an array of primitives. The latest version, Swagger UI 3.x, does not have this issue.

A possible workaround for 2.x is to add the x-examples.default key to the body parameter and specify the example value as a string:

  parameters:
    - in: body
      name: matrix
      description: blabla
      schema:
        type: array
        items:
          type: array
          items:
            type: number
            format: double
        example: [[1.0, 2.0],[3.0, 4.0]]
      x-examples:
        default: '[[1.0, 2.0],[3.0, 4.0]]'  # <-----
Improve this answer
Sign up to request clarification or add additional context in comments.

5 Comments

Thanks a lot for the explanatory answer. The data type is correctly recognized now. However, the example is still not shown. If entered in the swagger editor, it works. Could this be a bug in Flasgger?
@Damian It works fine for me in Swagger UI 2.2.10 - i.sstatic.net/b6a8W.png. You mention Flasgger - how do you specify the parameter definition in Flasgger? Which exactly version of Swagger UI does Flasgger use? (Check the comments at the top of the swagger-ui.js file.)
the version in swagger-ui.js is v.2.2.10. I specify the parameter directly in the docstring (i.imgur.com/8m274Zl.png). Isn't what you show in your screenshot the response variable? The example for the response works for me as well. It's just the parameter that's bugging me
@Damian: Thanks, I see now. The example at the top is the response example, but there's no request example (body example). I updated the answer to include the workaround for 2.x.
Fantastic. Thank you very much

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.