How to describe a model in Swagger for an array with simple objects?
Solution 1
Tony YUEN was close, but no cigar. This is the proper definition using YAML in OpenAPI/Swagger:
/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 a JSON-version of Swagger/OpenAPI
{
"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"
}
}
}
}
}
Solution 2
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"
}
}
}
}
}
}
Solution 3
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
Solution 4
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"
},
}
}
}
}
...
Solution 5
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....
razor
Updated on July 08, 2022Comments
-
razor almost 2 years
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" } ]
-
razor almost 10 yearsI was askking how to describe: [ { "name":"a" }, { "name":"b" }, { "name":"c" } ]
-
jrc over 7 yearsThis 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." -
Gobliins over 6 yearsis this possible without
application/json
? -
iBug over 6 yearsThank 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.
-
user1778602 about 6 yearsapplication/json is the default. You can remove it completely or even add xml as an alternative
-
emery almost 2 yearsGood answer. The key here is "type: array" with the "items:" under that, to express items inside the [ ] brackets