Specify an array of strings as body parameter in swagger API

Question

I would like to post an array of strings like

[
  "id1",
  "id2"
]

to a Swagger based API. In my swagger file, I have those lines:

paths:
  /some_url:
    post:
      parameters:
        - name: ids
          in: body
          required: true

What is the correct way to specify the type of ids as an array of strings?

Update:

According to the specification, the following should work in my option:

  parameters:
    - in: body
      description: xxx
      required: true
      schema:
        type: array
        items:
          type: string

https://github.com/Yelp/swagger_spec_validator does not accept it and returns a long list of convoluted errors, which look like the code expects some $ref.

Answer 1

Your description of an array of string is correct, but the parameter definition misses the name property to be valid.

Here's a full working example:

swagger: "2.0"  info:   title: A dummy title   version: 1.0.0  paths:   /path:     post:       parameters:         - in: body           description: xxx           required: true           name: a name           schema:             type: array             items:               type: string       responses:         default:           description: OK 

Try the online editor to check your OpenAPI (fka. Swagger) specs: http://editor.swagger.io/

Answer 2

I have created a swagger issue as the help provided by Arnaud, although is valid yaml, will give you NPE exceptions when trying to generate. You will need to provide an object like the following:

  myDataItem:
    type: object
    description: A list of values
    required:
      - values
    properties:
      values:
        type: array
        items:
            type: string

And then refer to it (in your post item etc):

  schema:
    $ref: "#/definitions/myDataItem"

For reference the github issue:

https://github.com/swagger-api/swagger-codegen/issues/6745

Note, the issue has been fixed in version 2.3.0 and higher, ideally you should upgrade to that version.

Answer 3

None of the answers worked for me. As it is stated in the following Baeldung article:

To better document the API and instruct the user, we can use the example label of how to insert values

So the full working example would be something like that:

swagger: "2.0"

info:
  title: A dummy title
  version: 1.0.0

paths:
  /path:
    post:
      parameters:
        - in: body
          description: xxx
          required: true
          name: a name
          schema:
            type: array
            items:
              type: string
            example: ["str1", "str2", "str3"]
      responses:
        default:
          description: OK

You can check how the Example Value is now better informed in the Swagger editor.