This question already has answers here:
How to return an array of objects in SwaggerHub?
(2 answers)
Closed 4 years ago.
I have this schema defined:
User:
type: object
required:
- id
- username
properties:
id:
type: integer
format: int32
readOnly: true
xml:
attribute: true
description: The user ID
username:
type: string
readOnly: true
description: The username
first_name:
type: string
description: Users First Name
last_name:
type: string
description: Users Last Name
avatar:
$ref: '#/components/schemas/Image'
example:
id: 10
username: jsmith
first_name: Jessica
last_name: Smith
avatar: image goes here
xml:
name: user
Works great. The GET /user/{id} call displays the sample data just fine.
I have a second schema that creates an array of the above schema:
ArrayOfUsers:
type: array
items:
type: object
required:
- id
- username
properties:
id:
type: integer
format: int32
xml:
attribute: true
description: The user ID
username:
type: string
description: The username
first_name:
type: string
description: Users First Name
last_name:
type: string
description: Users Last Name
avatar:
$ref: '#/components/schemas/Image'
This also works great. The GET /user call displays the proper structure in an array just fine.
But I'd rather not define this schema twice.
I would like to create a schema that utilizes the first one and stick in an array.
I have failed in this attempt.
I tried it this way:
UserArray:
type: array
items:
type: object
required:
- id
- username
properties:
things:
type: array
items:
oneOf:
- $ref: '#/components/schemas/User'
This attempt gives me an empty array:
[
{}
]
This is not my desired result.
Any hints on this?
An array of User objects is defined as follows:
UserArray:
type: array
items:
$ref: '#/components/schemas/User'
Related
I am new to Open API specification ( ia m using 3.0). I am playing with swagger Editor online tool and I am getting a weird error of:
"should NOT have additional properties
additionalProperty: Data1, Data2"
Here is sample of YAML file I am working with:
paths:
/api/assignment:
post:
tags:
- Assignment
summary: "Endpoint to create Resources in system"
description: "This endpoint will create blah blah"
operationId: CreateResource
parameters:
- name: assignment
in: body
description: "This is an object to be sent"
required: true
schema:
type: object
properties:
Ganesh:
type: integer
Test:
type: string
RefClaim:
Data1:
FirstName:
type: string
LastName:
type: string
Data2:
FirstName2:
type: string
LastName2:
type: string
I have seen all questions asked and tried with those but I could not get answer.
Note: I am using Open Api specification 3.0.1
There are a few issues:
1) in: body parameters are an OpenAPI 2.0 thing. OpenAPI 3.0 uses requestBody instead.
2) Nested objects also need the type: object and properties keywords.
The correct version is:
paths:
/api/assignment:
post:
tags:
- Assignment
summary: "Endpoint to create Resources in system"
description: "This endpoint will create blah blah"
operationId: CreateResource
requestBody: # <-----------
required: true
content:
application/json:
schema:
type: object
properties:
Ganesh:
type: integer
Test:
type: string
RefClaim:
type: object # <-----------
properties: # <-----------
Data1:
type: object # <-----------
properties: # <-----------
FirstName:
type: string
LastName:
type: string
Data2:
type: object # <-----------
properties: # <-----------
FirstName2:
type: string
LastName2:
type: string
VehicleBaseAttributes:
type: object
properties:
id:
type: integer
format: int64
model:
type: string
doors:
type: integer
VehicleExtendedAttributes:
type: object
properties:
$ref: '#/components/schemas/VehicleBaseAttributes'
pricehistory:
type: array
items:
title: PriceHistory
type: object
properties:
priceWOT:
type: number
taxes:
type: number
additionalCosts:
type: number
price:
type: number
createdByUserId:
type: string
createdDate:
type: string
dealerHistory:
type: array
items:
title: DealerHistory
type: object
properties:
name:
type: string
phone:
type: string
createdByUserId:
type: string
createdDate:
type: string
In the above example I intended to have a basic set of attributes defined, then offer an extended version that used the base version.
Obviously in the VehicleExtendedAttributes I don't want to nest the VehicleBaseAttributes in a separate attribute, instead for them to be added to the top level, resulting in an output of something like:
type: object
properties:
id:
type: integer
format: int64
model:
type: string
doors:
type: integer
pricehistory:
type: array
items:
title: PriceHistory
type: object
properties:
priceWOT:
type: number
taxes:
type: number
additionalCosts:
type: number
price:
type: number
createdByUserId:
type: string
createdDate:
type: string
dealerHistory:
type: array
items:
title: DealerHistory
type: object
properties:
name:
type: string
phone:
type: string
createdByUserId:
type: string
createdDate:
type: string
The problem is this results in an error:
Schema error at components.schemas['VehicleExtendedAttributes']
should have required property '$ref'
missingProperty: $ref
Jump to line 342
Schema error at components.schemas['VehicleExtendedAttributes']
should match exactly one schema in oneOf
Jump to line 342
Schema error at components.schemas['VehicleExtendedAttributes'].properties['$ref']
should be object
Jump to line 345
You need allOf to do model composition. The value of allOf is a list of subschemas ($referenced or inline) that together compose a single schema.
VehicleExtendedAttributes:
allOf:
- $ref: '#/components/schemas/VehicleBaseAttributes'
- type: object
properties:
pricehistory:
type: array
...
dealerHistory:
type: array
...
Further info:
Swagger Inheritance and Composition here on Stack Overflow
Composition and Inheritance (Polymorphism) section of the OpenAPI 3.0 Specification
Model Composition, Inheritance and Polymorphism
oneOf, anyOf, allOf, not
I am defining an API specification in SwaggerHub using OpenAPI 2.0. The /contacts request returns an array of contacts. The definition is below:
/contacts:
get:
tags:
- contacts
summary: Get all the contacts
description: This displays all the contacts present for the user.
operationId: getContact
produces:
- application/json
- application/xml
responses:
200:
description: successful operation
schema:
$ref: '#/definitions/AllContacts'
400:
description: Invalid id supplied
404:
description: Contact not found
500:
description: Server error
definitions:
AllContacts:
type: array
items:
- $ref: '#/definitions/ContactModel1'
- $ref: '#/definitions/ContactModel2'
ContactModel1:
type: object
properties:
id:
type: integer
example: 1
firstName:
type: string
example: 'someValue'
lastName:
type: string
example: 'someValue'
ContactModel2:
type: object
properties:
id:
type: integer
example: 2
firstName:
type: string
example: 'someValue1'
lastName:
type: string
example: 'someValue1'
For some reason, it only returns the second object not the whole array of objects.
I am using OpenAPI 2.0 and suspect that the arrays are not well supported in this version.
An array of objects is defined as follows. The value of items must be a single model that describes the array items.
definitions:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel'
ContactModel:
type: object
properties:
id:
type: integer
example: 1
firstName:
type: string
example: Sherlock
lastName:
type: string
example: Holmes
By default, Swagger UI displays the array examples with just one item, like so:
[
{
"id": 1,
"firstName": "Sherlock",
"lastName": "Holmes"
}
]
If you want the array example to include multiple items, specify the multi-item example in the array model:
definitions:
AllContacts:
type: array
items:
$ref: '#/definitions/ContactModel1'
example:
- id: 1
firstName: Sherlock
lastName: Holmes
- id: 2
firstName: John
lastName: Watson
I realise this is a bit offtopic, but I landed here looking for an example for OpenApi 3.0. For others looking for the same thing, this is how to do it:
paths:
/product-category:
get:
summary: 'Returns all product categories'
operationId: readProductCategory
tags:
- productCategory
responses:
'200':
description: 'Details about all product categories'
content:
application/json:
schema:
type: array
items:
allOf:
- $ref: '#/components/schemas/Identifier'
- $ref: '#/components/schemas/ProductCategory'
I'm fairly new to swagger and would appreciate some direction on good resources for learning.
I have a test project that I'm putting together and I am running into some issues.
I'm getting an error saying that the "parameters" in my "delete" block is not valid. It looks ok to me from what I've seen in the examples. But apparently I'm missing something. Any ideas?
swagger: "2.0"
info:
version: "2"
title: My Title
description: Provides services for vacation rentals site
termsOfService: Private
contact:
name: My Name
url: www.myurl.com
email: my#email.address
license:
name: MIT
url: http://opensource.org/licenses/MIT
schemes:
- http
host: myurl.com
basePath: /api
paths:
/guestbook:
get:
summary: Gets some persons
description: Returns a list containing all persons.
responses:
200:
description: A list of posts
schema:
type: array
items:
required:
- firstName
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
comment:
type: string
post:
summary: Adds a comment to the guestbook
description: Adds a comment to the guestbook
parameters:
- name: firstname
in: formData
required: true
type: string
- name: lastname
in: formData
required: true
type: string
- name: email
in: formData
required: true
type: string
- name: comment
in: formData
required: true
type: string
responses:
201:
description: Shows a successful post
'405':
description: Invalid input
/guestbook/{id}:
get:
summary: Gets a single post
description: Returns a single post
operationId: getPost
parameters:
- name: id
in: path
description: ID of pet to fetch
required: true
type: integer
format: int64
responses:
200:
description: A list of posts
schema:
type: array
items:
required:
- firstName
properties:
id:
type: number
firstName:
type: string
lastName:
type: string
email:
type: string
comment:
type: string
delete:
summary: Removes a post
description: Removes a post
operationId: deletePost
parameters:
- name: id
in: path
responses:
200:
description: Post has been removed
You just need to describe the id parameter in the delete /guestbook/{id} operation just like you did in get /guestbook/{id}.
delete:
summary: Removes a post
description: Removes a post
operationId: deletePost
parameters:
- name: id
in: path
description: ID of pet to fetch
required: true
type: integer
format: int64
responses:
200:
description: Post has been removed
You can also define this parameter once for all operations of path /guestbook/{id}:
/guestbook/{id}:
parameters:
- name: id
in: path
description: ID of pet to fetch
required: true
type: integer
format: int64
get:
summary: Gets a single post
description: Returns a single post
operationId: getPost
responses:
200:
description: A list of posts
schema:
type: array
items:
required:
- firstName
properties:
id:
type: number
firstName:
type: string
lastName:
type: string
email:
type: string
comment:
type: string
delete:
summary: Removes a post
description: Removes a post
operationId: deletePost
responses:
200:
description: Post has been removed
If you need to learn how to write OpenAPI (fka. Swagger) specification files, you can read my Writing OpenAPI/Swagger Specification Tutorial
I've been searching fruitlessly on how to swagger spec a POST body with a list inside of it. How do I do it? Here's what I have:
/groups:
post:
summary: Creates a group
parameters:
- name: body
in: body
schema:
properties:
name:
type: string
description:
type: string
groupType:
type: string
enum: [ "open", "closed", "secret" ]
users:
type: string list # <--------- a list of strings
responses:
201:
description: Group created
default:
description: Group creation failed
For property being an array of string, please refer to https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#L660 as an example:
photoUrls:
type: array
items:
type: string