I have an OpenAPI 3.0 definition in SwaggerHub at https://app.swaggerhub.com/apis/PHP-Point-Of-Sale/PHP-Point-Of-Sale/1.0#/customers/get_customers
The example response is [null] when I believe it should show example values based on how I setup the OpenAPI definition.
openapi: 3.0.0
...
paths:
/customers:
get:
tags:
- customers
summary: Search/list customers
description: ''
parameters:
- name: search
in: query
description: Search customers
required: false
schema:
type: string
- name: search_field
in: query
description: Search specific field
required: false
schema:
type: string
enum:
- first_name
- last_name
- email
- phone_number
- account_number
- custom_field_1
- custom_field_2
- custom_field_3
- custom_field_4
- custom_field_5
- custom_field_6
- custom_field_7
- custom_field_8
- custom_field_9
- custom_field_10
- name: offset
in: query
description: Offset to list customers
required: false
schema:
type: integer
minimum: 0
default: 0
- name: limit
in: query
description: Number of customers to get
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
'200':
description: successful operation
headers:
x-total-records:
description: Total number of results in search
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Customers'
application/xml:
schema:
$ref: '#/components/schemas/Customers'
'400':
description: Invalid parameter(s)
components:
schemas:
Customer:
type: object
allOf:
- $ref: '#/components/schemas/ExistingPerson'
- $ref: '#/components/schemas/NewCustomerWithImageUrl'
Customers:
type: array
items:
$ref: '#/components/schemas/Customer'
ExistingPerson:
type: object
properties:
person_id:
type: integer
format: uuid
example: 3
NewCustomerWithImageUrl:
allOf:
- $ref: '#/components/schemas/NewCustomer'
- type: object
properties:
image_url:
type: string
example: http://www.abc.xyz
NewCustomer:
type: object
allOf:
- $ref: '#/components/schemas/Person'
- type: object
properties:
company_name:
type: string
example: PHP Point Of Sale
tier_id:
type: integer
format: uuid
example: 0
account_number:
type: string
example: '3333'
taxable:
type: boolean
example: false
tax_certificate:
type: string
example: '1234'
override_default_tax:
type: boolean
example: false
tax_class_id:
type: integer
format: uuid
example: 0
balance:
type: number
format: float
example: 22.99
credit_limit:
example: null
points:
type: integer
format: int32
example: 333
disable_loyalty:
type: boolean
example: true
amount_to_spend_for_next_point:
type: number
format: float
readOnly: true
example: 10.00
remaining_sales_before_discount:
type: integer
format: int32
readOnly: true
example: 0
xml:
name: Customer
The issue seems to have been fixed and is no longer reproduced as of November 2018.
Original answer:
Your response example is displayed correctly in http://editor.swagger.io which (at the time of writing) uses Swagger UI 3.12.0.
It looks like SwaggerHub uses an older version of Swagger UI. You should contact SwaggerHub Support and ask them to update to the latest Swagger UI.
Related
I'm trying to add an object in an array, but this seems not be possible. I've tried the following, but I get always the error:
Property Name is not allowed.
This is shown for all items defined in the devices array. How can I define items in an array in OpenAPI?
/demo/:
post:
summary: Summary
requestBody:
description: Description.
required: true
content:
application/json:
schema:
type: object
properties:
Name:
type: string
Number:
type: array
items:
type: string
description:
type: string
type:
type: string
devices:
type: array
items:
Name:
type: string
descripiton:
type: string
Number:
type: integer
enabled:
type: boolean
required:
- Name
- Number
- devices
responses:
'201': # status code
description: Created.
'500':
description: Error.
'405':
description: Invalid body has been presented.
You need to add two extra lines inside items to specify that the item type is an object:
devices:
type: array
items:
type: object # <----------
properties: # <----------
Name:
type: string
descripiton:
type: string
Number:
type: integer
enabled:
type: boolean
This is the array of objects with examples:
components:
schemas:
abc:
xml:
wrapped : true
name: abc
type: array
items:
type: object
xml:
name: 'item'
properties:
Name:
type: string
age:
type: integer
enabled:
type: boolean
example:
- Name: no1
age: 18
enabled: true
- Name: no2
age: 20
enabled: false
json
xml
I am trying to create a swagger doc for a post meetings call. I am unsure how to add body fields under parameters (like meeting.name, meeting.time, meeting.duration etc). I get the error in the parameters "allowedValues: path, query, header, cookie". I am unsure which one to pick from here? I am done this previously by writing "-in: body" but body doesn't seem to be an option here.
openapi: '3.0.0'
info:
title: WebcastCreateMeeting
version: "1.1"
servers:
- url: https://api.webcasts.com/api
paths:
'/event/create/{event_title}/{folder_id}/{type}/{scheduled_start_time}/{scheduled_duration}/{timezone}/{region}/{acquisition_type}/{audience_capacity}/{event_expiration_months}/{token}':
post:
tags:
- CreateMeetingCallbody
summary: EventGM
parameters:
- in: path
name: token
description: the auth token
required: true
schema:
type: string
example: 123j1lkj3lk1j3i1j23l1kj3k1j2l3j12l3j1l2
- in: path
name: event_title
description: Name of the event from Cvent
required: true
schema:
type: string
- in: body
name: user
description: this is a test user
schema:
type: object
required:
- username
properties:
username:
type: string
- in: path
name: folder_id
description: ID of the folder under whihc the Meeting is to be added
required: true
schema:
type: string
- in: path
name: type
description: Type of the Meeting
required: true
schema:
type: string
- in: path
name: scheduled_start_time
description: Start time of
required: true
schema:
type: string
format: date-time
- in: path
name: scheduled_duration
description: Duration
required: true
schema:
type: integer
example: 60
- in: path
name: timezone
description: TimeZone of the event LU table
required: true
schema:
type: string
- in: path
name: region
description: Region from Zoom
required: true
schema:
type: integer
example: 1
- in: path
name: acquisition_type
description: To be added from GM
required: true
schema:
type: integer
example: 0
- in: path
name: audience_capacity
description: To be added for capacity
required: true
schema:
type: integer
- in: path
name: event_expiration_months
description: the month it expires on.
required: true
schema:
type: integer
example: 3
responses:
200:
description: This would be the response.
content:
application/json;charset=utf-8:
schema:
type: array
items:
properties:
scheduled_duration:
type: integer
example: 30
event_id:
type: integer
example: 0000000
audience_capacity:
type: integer
example: 30
folder_name:
type: string
example: Folder_Name
viewer_link:
type: string
example: https://viewer_link
scheduled_start_time:
type: string
format: date-time
example: 1541674800000
scheduled_player_close_time:
type: integer
example: 10
event_title:
type: string
[![enter image description here][1]][1]
Kindly advise on how to describe the body fields I am supposed to pass in the code.
Thanks
Got it, its passed separately in "requestbody" check here
Thanks.
In OpenApi 3 I can specify multiple return schema for the same status code.
As an example: given the endpoint /something and it can either return an ApiResultOk or ApiResultError.
(The example if from https://stackoverflow.com/a/47453822/3430316)
openapi: 3.0.0
paths:
/something:
get:
responses:
'200':
description: Result
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiResultOk'
- $ref: '#/components/schemas/ApiResultError'
components:
schemas:
ApiResultOk:
type: object
properties:
result:
type: boolean
enum: [true]
token:
type: string
required:
- result
- token
ApiResultError:
type: object
properties:
result:
type: boolean
enum: [false]
errorCode:
type: string
errorMsg:
type: string
Is it possible to specify different headers for the related schemas?
(As a workaround, headers can be optional with the description when it is provided.)
Let's say I have some simple Order > OrderLines > Product Data Model in an OpenAPI document.
The Components part would look like this:
components:
schemas:
Order:
required:
- orderId
properties:
orderId:
type: integer
orderlines:
type: array
items:
$ref: '#/components/schemas/OrderLine'
OrderLine:
required:
- orderLineId
- product
- price
properties:
orderLineId:
type: integer
product:
$ref: '#/components/schemas/Product'
price:
type: integer
Product:
required:
- productId
- name
x-keys:
- productId
properties:
productId:
type: integer
name:
type: string
When building a path to define an api to get a specific OrderLine on an Order, this would look like this:
paths:
/orders/{orderId}/orderlines/{orderLineId}:
get:
operationId: getOrderLine
parameters:
- in: path
name: orderId
schema:
type: integer
required: true
- in: path
name: orderLineId
schema:
type: integer
required: true
Now, the defined orderId parameters actually refers to the orderId property of the Order Component. And the same goes for parameter orderLineId which refers to the orderLineId property of Component OrderLine.
So is it possible to actually refer to these properties in the parameter definition instead of duplicating the type information of the properties?
I mean is it somehow possible to do something like this:
paths:
/orders/{orderId}/orderlines/{orderLineId}:
get:
operationId: getOrderLine
parameters:
- in: path
name: orderId
$ref: #components/schemas/Order/properties/orderId
required: true
- in: path
name: orderLineId
$ref: #components/schemas/OrderLine/properties/orderLineId
required: true
First of all, always add type: object to your object definitions; the properties keyword alone is not enough to indicate the object type. The type is not inferred from other keywords, and no type actually means "any type".
As for your question - sure, it's possible to $ref individual property definitions. Your example is almost correct, you just need to:
Put the $ref inside the parameter schema.
Replace #components with #/components.
Enclose the reference values (#/components/...) in quotes to prevent them from being parsed as YAML comments.
paths:
/orders/{orderId}/orderlines/{orderLineId}:
get:
operationId: getOrderLine
parameters:
- in: path
name: orderId
schema:
$ref: '#/components/schemas/Order/properties/orderId'
required: true
- in: path
name: orderLineId
schema:
$ref: '#/components/schemas/OrderLine/properties/orderLineId'
required: true
However, referencing property definitions is uncommon, and some tools may have problems handling such references. It's best to define separate schemas for all definitions you want to $ref:
components:
schemas:
OrderId: # <-------
type: integer
OrderLineId: # <-------
type: integer
Order:
type: object
required:
- orderId
properties:
orderId:
$ref: '#/components/schemas/OrderId' # <-------
...
OrderLine:
type: object
required:
- orderLineId
- product
- price
properties:
orderLineId:
$ref: '#/components/schemas/OrderLineId' # <-------
...
paths:
/orders/{orderId}/orderlines/{orderLineId}:
get:
operationId: getOrderLine
parameters:
- in: path
name: orderId
schema:
$ref: '#/components/schemas/OrderId' # <-------
required: true
- in: path
name: orderLineId
schema:
$ref: '#/components/schemas/OrderLineId' # <-------
required: true
I try to generate a REST API definition with Swagger and YAML,
but at $ref: '#/definitions/Token' I get the error
Bad indentation of a mapping entry
parameters:
- name: environmentID
in: query
description: id from the gamificationenvironment
required: true
type: integer
format: int32
- name: authorizationToken
in: query
description: Authorization token to create a new environment
required: true
schema:
type: object
--> Error $ref: '#/definitions/Token'
responses:
201:
description: GamificationID for the Admin
schema:
type: object
items:
$ref: '#/definitions/Environment'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
definitions:
Token:
required:
- authentificationKey
- user
properties:
authentificationKey:
type: string
senderID:
type: integer
format: int32
user:
type: string
type: integer
format: int64
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string
My Question is:
Why does the Mapping with $ref is working at the responses and
at the paramets I get an error ?
This part is syntactically incorrect:
required: true
schema:
type: object
$ref: '#/definitions/Token'
schema: should be at same level as required:.