How to describe a model in Swagger for an array with simple objects?

Question

I have a REST services to document, some of them accepts simple array like:

[
  { "name":"a" },
  { "name":"b" },
  { "name":"c" }
]

How do I describe this in Swagger model section ? I can only create 'named array' like

model {
properties: { "arr": { "type":"array", ......

but it describes data like this:

"arr": [
  { "name":"a" },
  { "name":"b" },
  { "name":"c" }
]

If you want to avoid typing by hand, you could try this JSON to Swagger Definitions converter: roger13.github.io/SwagDefGen — Roger
– Roger, Commented Feb 2, 2017 at 15:29
use anyOf . Refer : json-schema.org/understanding-json-schema/reference/… — nilakantha singh deo
– nilakantha singh deo, Commented Feb 19, 2019 at 10:25

Helen · Accepted Answer · 2023-03-09 15:35:45Z

Tony YUEN was close, but no cigar. This is the proper definition using YAML in OpenAPI/Swagger 2.0:

  /test:
    post:
      summary: test 123
      description: test 123
      parameters:
        - name: param1
          in: body
          required: true
          description: test param1
          schema:
              $ref: '#/definitions/stackoverflow'
      responses:
        200:
          description: OK

This produces:

stackoverflow2[
  {
     name: string
  }
]

Tony's example produces:

[
  stackoverflow { 
                 name: string
  }
]

Complete Swagger/OpenAPI as YAML (copy & paste):

swagger: '2.0'

################################################################################
#                              API Information                                 #
################################################################################
info:
  version: "Two-point-Oh!"
  title: Simple objects in array test
  description: |
    Simple objects in array test

################################################################################
#                                   Parameters                                 #
################################################################################

paths:
  /test:
    post:
      summary: Array with named objects
      description: Array with named objects
      parameters:
        - name: param1
          in: body
          required: true
          description: test param1
          schema:
            type: array
            items:
              $ref: '#/definitions/stackoverflow'
      responses:
        200:
          description: OK
  /test2:
    post:
      summary: Array with simpel (nameless) objects
      description: Array with simpel (nameless)  objects
      parameters:
        - name: param1
          in: body
          required: true
          description: test param1
          schema:
              $ref: '#/definitions/stackoverflow2'
      responses:
        200:
          description: OK
definitions:
  stackoverflow:
    type: object
    properties:
      name:
        type: string
        description: name of the object
  stackoverflow2:
    type: array
    items:
      type: object
      properties:
        name:
          type: string
          description: name of the object

Here's the JSON version of Swagger/OpenAPI 2.0:

{
  "swagger" : "2.0",
  "info" : {
    "description" : "Simple objects in array test\n",
    "version" : "Two-point-Oh!",
    "title" : "Simple objects in array test"
  },
  "paths" : {
    "/test" : {
      "post" : {
        "summary" : "Array with named objects",
        "description" : "Array with named objects",
        "parameters" : [ {
          "in" : "body",
          "name" : "param1",
          "description" : "test param1",
          "required" : true,
          "schema" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/definitions/stackoverflow"
            }
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK"
          }
        }
      }
    },
    "/test2" : {
      "post" : {
        "summary" : "Array with simpel (nameless) objects",
        "description" : "Array with simpel (nameless)  objects",
        "parameters" : [ {
          "in" : "body",
          "name" : "param1",
          "description" : "test param1",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/stackoverflow2"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK"
          }
        }
      }
    }
  },
  "definitions" : {
    "stackoverflow" : {
      "type" : "object",
      "properties" : {
        "name" : {
          "type" : "string",
          "description" : "name of the object"
        }
      }
    },
    "stackoverflow2" : {
      "type" : "array",
      "items" : {
        "$ref" : "#/definitions/stackoverflow2_inner"
      }
    },
    "stackoverflow2_inner" : {
      "properties" : {
        "name" : {
          "type" : "string",
          "description" : "name of the object"
        }
      }
    }
  }
}

JoSSte · Accepted Answer · 2024-06-10 07:17:11Z

16

Considering the format of the array you mentioned

[
  { "name":"a" },
  { "name":"b" },
  { "name":"c" }
]

I guess the following format can be used:

    paths:
      /test:
        post:
          description: Test request
          operationId: test
          parameters:
            - in: body
              name: requestParameter
              required: true
              schema:
                type: array
                items:
                  properties:
                    name:
                      type: string
          responses:
            '200':
              description: Success response

edited Jun 10, 2024 at 7:17

JoSSte

3,4427 gold badges43 silver badges63 bronze badges

answered Apr 9, 2018 at 10:05

Nagaraj subramanian

1611 silver badge2 bronze badges

2 Comments

emery Over a year ago

Good answer. The key here is "type: array" with the "items:" under that, to express items inside the [ ] brackets

c8999c 3f964f64 Over a year ago

how do you do multiple items in this format?

user1778602 · Accepted Answer · 2018-04-19 03:46:04Z

15

Paste this to http://editor.swagger.io/#/ and click on "try this operation"

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Privacy-Service API"
  },
  "paths": {
    "/allNames": {
      "post": {
        "consumes": [
          "application/json",
          "application/xml"
        ],
        "produces": [
          "application/json",
          "application/xml"
        ],
        "parameters": [
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/ArrayOfNames"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of names",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "ArrayOfNames": {
      "type": "array",
      "items": {
        "minItems": 1,
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

edited Apr 19, 2018 at 3:46

answered Dec 21, 2016 at 21:20

user1778602

5805 silver badges9 bronze badges

2 Comments

Gobliins Over a year ago

is this possible without application/json ?

user1778602 Over a year ago

application/json is the default. You can remove it completely or even add xml as an alternative

Meruemu · Accepted Answer · 2015-07-27 22:56:15Z

6

It probably looks like this:

    ...
    "parameters" : [{
      "name" : "whatEverThatArrayCalled",
      "type" : "array",
      "items" : {
        "$ref" : "whatEverThatArrayCalled"
      }
      ...
    }],
    "models" : {
   {
    "id" : "whatEverThatArrayCalled",
    "properties": 
        {
       "whatEverThatArrayCalled" :
            {
         "type" : "array",
         "items":{"name":"a",
                  "name":"b",
                  "name":"c"
                  },

             }
         }
    }
 }

...

answered Jul 27, 2015 at 22:56

Meruemu

6211 gold badge11 silver badges30 bronze badges

Comments

Gobliins · Accepted Answer · 2018-01-31 11:31:42Z

4

  parameters:
  - name: "items"
    in: "formData"
    description: "description"
    required: "true"
    type: "array"
    items:
      type: "object"
      additionalProperties:
        properties:
          name:
            type: "string"

According to their docs https://swagger.io/docs/specification/data-models/dictionaries/, this should result in an array with objects that have a property called name and datatype is string.
It can be accessed over the requests body, something like request.body.items

Update:

it seems like it is enough to do (without the additionalproperties):

items:
  type: object
  properties:
    name:
      type: string

Now you got the items where each has a key called name and a corresponding value.

If it is this, what the TO was asking for....

edited Jan 31, 2018 at 11:31

answered Jan 22, 2018 at 14:44

Gobliins

4,09618 gold badges73 silver badges131 bronze badges

2 Comments

iBug Over a year ago

Thank you for this code snippet, which might provide some limited, immediate help. A proper explanation would greatly improve its long-term value by showing why this is a good solution to the problem, and would make it more useful to future readers with other, similar questions. Please edit your answer to add some explanation, including the assumptions you've made.

Tirath Sharma Over a year ago

I have sent data in same way but getting validation error that it is not an array.

*    - in: formData  *      name: car_maintenance_part  *      type: array  *      items:  *          type: object  *          properties:  *              description:  *                  type: string  *                  description: add description  *                  required: true  *              quantity:  *                  type: number  *                  description: 0.00  *                  required: true

Dongminator · Accepted Answer · 2016-10-06 01:56:48Z

3

I tried the follwoing in the editor.swagger.io, it satisfies the request of this question and works. The POST request body expects an array. The array is composed of 'stackoverflow' items. Each item is an object, that has name property.

paths:
  /test:
    post:
      summary: test 123
      description: test 123
      parameters:
        - name: param1
          in: body
          required: true
          description: test param1
          schema:
            type: array
            items:
              $ref: '#/definitions/stackoverflow'
      responses:
        200:
          description: OK
definitions:
  stackoverflow:
    type: object
    properties:
      name:
        type: string
        description: name of the object

answered Oct 6, 2016 at 1:56

Dongminator

84213 silver badges17 bronze badges

1 Comment

jrc Over a year ago

This is the correct answer. The key is in: body. According to the Swagger spec: "Since there can only be one payload, there can only be one body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only."

Tony YUEN · Accepted Answer · 2013-11-29 08:09:37Z

0

If my understanding is correct, I think the following may what you want.

As you mentioned,

some of them accepts simple array

Then it would be passed through a parameter.

"parameters" : [{
  "name" : "param_name",
  "type" : "array",
  "items" : {
    "$ref" : "M"
  }
  ...
}]
...

For model section:

"models" : {
  "M": {
    "id" : "M",
    "properties": {
       "name" : {
         "type" : "string"
       }
    }
  }

answered Nov 29, 2013 at 8:09

Tony YUEN

4924 silver badges4 bronze badges

1 Comment

razor Over a year ago

I was askking how to describe: [ { "name":"a" }, { "name":"b" }, { "name":"c" } ]

Collectives™ on Stack Overflow

How to describe a model in Swagger for an array with simple objects?

7 Answers 7

Comments

2 Comments

2 Comments

Comments

2 Comments

1 Comment

1 Comment

Linked

Hot Network Questions

Collectives™ on Stack Overflow

7 Answers 7

Comments

2 Comments

2 Comments

Comments

2 Comments

1 Comment

1 Comment

Linked

Related