58

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.

Improve this question

5 Answers 5

Reset to default
73

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/

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

1 Comment

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.
17

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.

Improve this answer

Comments

14

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.

Improve this answer

Comments

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
Improve this answer

Comments

3

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.

Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.