How to describe a model in Swagger for an array with simple objects?
RestSwaggerSwagger UiRest Problem Overview
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" }
]
Rest Solutions
Solution 1 - Rest
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 - Rest
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 - Rest
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 - Rest
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 - Rest
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....
Solution 6 - Rest
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
Solution 7 - Rest
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"
}
}
}