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.

Krebs

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/

Stpierre

It should be noted with the latest swagger codegen (2-2-3) this construct will give a null pointer exception. You will have to use a reference to a type instead. – Archpriest

Answer 2

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.

Hollis

Answer 3

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.

Archpriest

Answer 4

For Array containing Object as it's content, definition for Object can be also expressed using definitions & $ref. Example:

schema:
    type: array
    items:
        $ref: '#/definitions/ObjectSchemaDefinition'
definitions:
    ObjectSchemaDefinition:
        type: string

Rissole

Answer 5

The answer with the most votes got me in the right direction. I just needed an example of an array of objects where each one of them had a property which was an array of strings with more than one value in the strings array. Thanks to the documentation I got it working like this:

MyObject:
  type: object
  properties:
    body:
      type: array
      items:
        type: object
        properties:
          type: 
            type: string
          values: 
            type: array
            items:
              type: string
      example: 
        - type: "firstElement"
          values: ["Active", "Inactive"]
        - type: "SecondElement"
          values: ["Active", "Inactive"]

One thing to keep in mind is that indentation is of paramount importance to swagger. If you don't indent things well, swagger will give you strange error messages.

Lichenology