How to write documentation in swagger for array of objects. This is my code, but I don't know how to access data in array of objects.
{
"first_name":"Sam",
"last_name":"Smith",
"reservations":[
{
"chkin_date":"2016-03-31",
"chkout_date":"2016-04-08",
"adults":1,
"children":2,
"chdage":[2,3]
},
{
"chkin_date":"2016-03-30",
"chkout_date":"2016-04-03",
"adults":1,
"children":2,
"chdage":[2,3,5]
}
]
}
Here you go:
definitions:
SomeObject:
properties:
first_name:
type: string
example: Sam
last_name:
type: string
example: Smith
reservations:
type: array
items:
$ref: '#/definitions/Reservation'
Reservation:
properties:
chkin_date:
type: string
format: date
example: 2016-03-31
chkout_date:
type: string
format: date
example: 2016-04-08
adults:
type: integer
format: int32
example: 1
children:
type: integer
format: int32
example: 2
chdage:
type: array
items:
type: integer
format: int32
Related
I have an input in the below format:
{"value" : {"codes": ["123","234"]} }
I have a swagger document as below but it does not yield the above result
/v1/search:
post:
summary: Get values
description: Get values
parameters:
- name: value
in: body
schema:
properties:
value:
type: array
items:
$ref: "#/definitions/Values"
definitions:
Values:
type: object
properties:
codes:
type: string
Any leads would be appreciated.
Try this. I used Value and Codes as schema names, but feel free to change them as you see fit.
- name: value
in: body
schema:
$ref: '#/definitions/Value'
definitions:
Value:
type: object
properties:
value:
$ref: '#/definitions/Codes'
Codes:
type: object
properties:
codes:
type: array
items:
type: string
I've an OpenAPI contract like this:
openapi: 3.0.1
info:
title: Internal API
version: ''
tags:
- name: Calendar
description: Api for Calendar resource
paths:
'/api/v1/appointments/{id}':
get:
tags:
- Calendar
summary: Get the given appointment
description: Get the given appointment
operationId: findById
parameters:
- name: id
in: path
description: The appointment Id
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Successful operation
content:
application/vnd.widget+json:
schema:
$ref: '#/components/schemas/AppointmentWidgetDto'
application/json:
schema:
$ref: '#/components/schemas/Appointment'
components:
schemas:
AppointmentWidgetDto:
required:
- contactEmail
- contactName
- contactPhone
- endDate
- startDate
- store
- title
type: object
properties:
store:
$ref: '#/components/schemas/Store'
title:
maxLength: 255
minLength: 0
type: string
description:
maxLength: 1024
minLength: 0
type: string
type:
maxLength: 50
minLength: 0
type: string
icon:
maxLength: 50
minLength: 0
type: string
startDate:
type: string
format: date-time
endDate:
type: string
format: date-time
contact:
$ref: '#/components/schemas/Contact'
contactName:
type: string
contactEmail:
type: string
contactPhone:
type: string
AuditUser:
type: object
properties:
sid:
type: string
fullName:
type: string
Contact:
required:
- billingCountry
- personType
- preset
- publicAdministration
- shippingCountry
- status
- type
type: object
properties:
id:
type: integer
format: int64
sid:
type: string
createdBy:
$ref: '#/components/schemas/AuditUser'
createdDate:
type: string
format: date-time
lastModifiedDate:
type: string
format: date-time
lastModifiedBy:
$ref: '#/components/schemas/AuditUser'
version:
type: integer
format: int64
userInputTime:
type: integer
format: int64
type:
type: string
enum:
- CUSTOMER
- SUPPLIER
- CUSTOMER_SUPPLIER
- SUBCONTRACTOR
personType:
type: string
enum:
- NATURAL_PERSON
- LEGAL_PERSON
extCode:
maxLength: 50
minLength: 0
type: string
lotteryCode:
maxLength: 8
minLength: 0
type: string
firstName:
type: string
lastName:
type: string
companyName:
type: string
fullName:
type: string
readOnly: true
gender:
type: string
enum:
- MALE
- FEMALE
- OTHER
birthDate:
type: string
format: date
birthCity:
type: string
job:
maxLength: 100
minLength: 0
type: string
billingAddress:
type: string
billingZipCode:
type: string
billingCity:
type: string
billingDistrict:
type: string
billingCountry:
maxLength: 2
minLength: 2
type: string
shippingAddress:
type: string
shippingZipCode:
type: string
shippingCity:
type: string
shippingDistrict:
type: string
shippingCountry:
maxLength: 2
minLength: 2
type: string
taxCode:
type: string
vatNumber:
type: string
landlinePhone:
type: string
mobilePhone:
type: string
fax:
type: string
email:
type: string
certifiedEmail:
type: string
workingDistance:
type: string
enum:
- FAR_NEAR
- INTERMEDIATE_NEAR
- NEAR
- FAR_INTERMEDIATE
bankName:
type: string
iban:
type: string
swift:
type: string
publicAdministration:
type: boolean
sdiAccountId:
type: string
store:
$ref: '#/components/schemas/Store'
preset:
type: boolean
avatar:
type: boolean
status:
type: string
enum:
- ACTIVE
- DECEASED
completenessScore:
type: number
readOnly: true
tags:
type: string
age:
type: integer
format: int32
Store:
required:
- address
- city
- code
- country
- district
- name
- whatsAppEnabled
- zipCode
type: object
properties:
id:
type: integer
format: int64
sid:
type: string
createdBy:
$ref: '#/components/schemas/AuditUser'
createdDate:
type: string
format: date-time
lastModifiedDate:
type: string
format: date-time
lastModifiedBy:
$ref: '#/components/schemas/AuditUser'
version:
type: integer
format: int64
userInputTime:
type: integer
format: int64
name:
type: string
code:
type: string
extCode:
maxLength: 50
minLength: 0
type: string
address:
type: string
zipCode:
type: string
city:
type: string
district:
type: string
country:
maxLength: 2
minLength: 2
type: string
landlinePhone:
type: string
mobilePhone:
type: string
whatsAppEnabled:
type: boolean
fax:
type: string
email:
type: string
certifiedEmail:
type: string
openingHours:
maxLength: 1024
minLength: 0
type: string
contactMinScore:
maximum: 10
minimum: 0
type: number
Agent:
required:
- country
- email
- firstName
- gender
- language
- lastName
- user
- verified
type: object
properties:
id:
type: integer
format: int64
sid:
type: string
createdBy:
$ref: '#/components/schemas/AuditUser'
createdDate:
type: string
format: date-time
lastModifiedDate:
type: string
format: date-time
lastModifiedBy:
$ref: '#/components/schemas/AuditUser'
version:
type: integer
format: int64
userInputTime:
type: integer
format: int64
user:
$ref: '#/components/schemas/User'
firstName:
type: string
lastName:
type: string
gender:
type: string
enum:
- MALE
- FEMALE
- OTHER
color:
maxLength: 30
minLength: 0
type: string
employeeId:
type: string
address:
type: string
zipCode:
type: string
city:
type: string
district:
type: string
country:
maxLength: 2
minLength: 2
type: string
birthDate:
type: string
format: date
taxCode:
type: string
vatNumber:
type: string
landlinePhone:
type: string
mobilePhone:
type: string
email:
type: string
verified:
type: boolean
readOnly: true
language:
maxLength: 2
minLength: 2
type: string
iban:
type: string
swift:
type: string
stores:
uniqueItems: true
type: array
items:
$ref: '#/components/schemas/Store'
avatar:
type: boolean
readOnly: true
tourCompleted:
type: boolean
readOnly: true
enabled:
type: boolean
writeOnly: true
password:
type: string
writeOnly: true
lastPasswordUpdate:
type: string
format: date-time
username:
type: string
roles:
uniqueItems: true
type: array
items:
type: string
enum:
- ROLE_ADMIN
userSid:
type: string
Appointment:
required:
- allDay
- endDate
- startDate
- status
- store
- title
type: object
properties:
id:
type: integer
format: int64
sid:
type: string
createdBy:
$ref: '#/components/schemas/AuditUser'
createdDate:
type: string
format: date-time
lastModifiedDate:
type: string
format: date-time
lastModifiedBy:
$ref: '#/components/schemas/AuditUser'
version:
type: integer
format: int64
userInputTime:
type: integer
format: int64
store:
$ref: '#/components/schemas/Store'
title:
maxLength: 255
minLength: 0
type: string
description:
maxLength: 1024
minLength: 0
type: string
color:
maxLength: 30
minLength: 0
type: string
type:
maxLength: 50
minLength: 0
type: string
icon:
maxLength: 50
minLength: 0
type: string
location:
maxLength: 255
minLength: 0
type: string
startDate:
type: string
format: date-time
endDate:
type: string
format: date-time
allDay:
type: boolean
contact:
$ref: '#/components/schemas/Contact'
contactName:
type: string
contactEmail:
type: string
contactPhone:
type: string
agent:
$ref: '#/components/schemas/Agent'
agentName:
type: string
status:
type: string
readOnly: true
enum:
- TO_APPROVE
- VALID
- CANCELED
- DECLINED
GrantedAuthority:
type: object
properties:
authority:
type: string
User:
required:
- enabled
- fullName
- roles
- username
type: object
properties:
id:
type: integer
format: int64
sid:
type: string
createdBy:
$ref: '#/components/schemas/AuditUser'
createdDate:
type: string
format: date-time
lastModifiedDate:
type: string
format: date-time
lastModifiedBy:
$ref: '#/components/schemas/AuditUser'
version:
type: integer
format: int64
userInputTime:
type: integer
format: int64
fullName:
type: string
username:
maxLength: 255
minLength: 3
type: string
enabled:
type: boolean
readOnly: true
roles:
maxItems: 2147483647
minItems: 1
uniqueItems: true
type: array
items:
type: string
enum:
- ROLE_ADMIN
accountNonExpired:
type: boolean
credentialsNonExpired:
type: boolean
authorities:
type: array
items:
$ref: '#/components/schemas/GrantedAuthority'
accountNonLocked:
type: boolean
I want my endpoint /api/v1/appointments/{id} return 2 different representations of my resource Appointment: the full resource and a light one (with less data).
I thought using content's schema is the right thing to do, so the client can easily decide what it wants.
I tried to generate some clients from this contract using Swagger editor and OpenApi generator but I see these Warning:
[WARNING] Multiple schemas found in the OAS 'content' section, returning only the first one (application/vnd.widget+json)
and my client, as expected from that message, has only one method that returns only 1 representation of the resource.
I found this bug https://github.com/OpenAPITools/openapi-generator/issues/144, but at the same time I think this is a very basic concept of HTTP/REST and I'm bit surpriced it doesn't work.
Indeed I'm questioning myself doing something wrong. Is there a way to describe a single endpoint returning different representations of the same resouce (OpenApi contract) generating the client with both methods needed to get the already mentioned resource's representations?
I have the following API definition in SwaggerHub:
swagger: '2.0'
info:
description: defaultDescription
version: '0.1'
title: defaultTitle
host: swapi.co
paths:
/api/people:
get:
produces:
- application/json
parameters:
- name: search
in: query
required: false
type: string
x-example: luke
responses:
'200':
description: Definition generated from Swagger Inspector
schema:
$ref: '#/definitions/Model0'
responseSchema:
$ref: '#/definitions/Model0'
definitions:
Results:
properties:
name:
type: string
height:
type: string
mass:
type: string
hair_color:
type: string
skin_color:
type: string
eye_color:
type: string
birth_year:
type: string
gender:
type: string
homeworld:
type: string
films:
type: array
items:
type: string
species:
type: array
items:
type: string
vehicles:
type: array
items:
type: string
starships:
type: array
items:
type: string
created:
type: string
edited:
type: string
url:
type: string
Model0:
properties:
count:
type: integer
format: int32
next:
type: object
previous:
type: object
results:
type: array
items:
$ref: '#/definitions/Results'
I cannot make this basic GET command to bring back the data I'm seeking. It only returns this:
TypeError: Failed to fetch
I'm unsure if it's a syntax issue, or possibly spacing, but I'm also getting an error for line 19 that reads:
should NOT have additional properties
additionalProperty: responseSchema, description, schema
Any ideas what is wrong?
https://swapi.co seems to be HTTPS-only, so you need to add
schemes:
- https
to you API definition to specify the protocol for requests.
but I'm also getting an error for line 19 that reads: "should NOT have additional properties additionalProperty: responseSchema, description, schema".
Remove these lines:
responseSchema:
$ref: '#/definitions/Model0'
There's no responseSchema keyword in OpenAPI.
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
Code below:
definitions:
Result:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
FindUID:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
data:
type: object
properties:
uid:
type: integer
format: int64
FindUsername:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
data:
type: object
properties:
username:
type: string
As you can see, the first part of FindUID and FindUsername is the same as Result. How to replace those duplicate code with Result?
You can compose definitions using allOf, here's a full example where Result is used in FindUID and FindUsername:
swagger: '2.0'
info:
description: Example API Description
title: Example Title
version: 1.0.0
paths: {}
definitions:
Result:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
FindUID:
allOf:
- $ref: "#/definitions/Result"
- type: object
properties:
data:
type: object
properties:
uid:
type: integer
format: int64
FindUsername:
allOf:
- $ref: "#/definitions/Result"
- type: object
properties:
data:
type: object
properties:
username:
type: string
More about this here: https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-4-advanced-data-modeling/ (disclosure: I wrote this tutorial)