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: https://roger13.github.io/SwagDefGen/ — Roger, Feb 02 '17 at 15:29
use anyOf . Refer : https://json-schema.org/understanding-json-schema/reference/combining.html — nilakantha singh deo, Feb 19 '19 at 10:25

score 38 · Answer 1 · edited Mar 09 '23 at 15:35

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"
        }
      }
    }
  }
}

user1778602 · Answer 2 · 2018-04-19T03:46:04.130

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"
          }
        }
      }
    }
  }
}

application/json is the default. You can remove it completely or even add xml as an alternative — user1778602, Apr 19 '18 at 03:46

score 13 · Answer 3 · edited Apr 09 '18 at 10:29

13

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 Apr 09 '18 at 10:29

André Kool

4,880
12
34
44

answered Apr 09 '18 at 10:05

Nagaraj subramanian

131
1
2

Good answer. The key here is "type: array" with the "items:" under that, to express items inside the [ ] brackets – emery May 27 '22 at 21:24

score 6 · Answer 4 · answered Jul 27 '15 at 22:56

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"
                  },

             }
         }
    }
 }

...

Gobliins · Answer 5 · 2018-01-31T11:31:42.453

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 '18 at 11:31

answered Jan 22 '18 at 14:44

Gobliins

3,848
16
67
122

2

Thank you for this code snippet, which might provide some limited, immediate help. A [proper explanation would greatly improve its long-term value](//meta.stackexchange.com/q/114762/350567) 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. – iBug Jan 23 '18 at 05:35
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 ``` – Tirath Sharma Mar 22 '23 at 11:26

score 3 · Answer 6 · answered Oct 06 '16 at 01:56

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

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." — jrc, Nov 07 '16 at 20:04

score 0 · Answer 7 · answered Nov 29 '13 at 08:09

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 '13 at 08:09

Tony YUEN

492
4
4

14

I was askking how to describe: [ { "name":"a" }, { "name":"b" }, { "name":"c" } ] – razor Aug 05 '14 at 08:41

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

7 Answers7

Linked

Related