I'm trying to figure out how to use top level parameters and then, at the operation level,use a $ref to refer to the definition that was declared at the top level object.
Here is what the YAML looks like but when I try this I get an empty parameter displayed. Anyone know the correct syntax for this?
swagger: '2.0'
info:
version: 0.1.0
title: Customer API
parameters:
index:
name: index
in: query
description: Specifies the offset of the first item to be returned. The default value is 0, which starts at the beginning.
type: integer
default: 0
minimum: 0
paths:
/customers:
get:
parameters:
- $ref: '#/parameters/index'
responses:
200:
description: List all customers
schema:
$ref: '#/definitions/Customers'
definitions:
Customer:
properties:
name:
type: string
id:
type: integer
format: int32
Customers:
properties:
startIndex:
type: integer
itemsPerPage:
type: integer
totalResults:
type: integer
entries:
type: array
$ref: Customer
The support for this has yet to be implemented in swagger-ui. See https://github.com/swagger-api/swagger-ui/issues/621.
Related
I am trying to define my API using OpenAPI version 3.0. I am trying to generate a YAML file which has four maps, and each map contains a different information. How can I create a YAML file to achieve that goal? I know that my components are not right because of which I am not getting the right result.
Request body should be like this:
[
UserInformation{FirstName, LastName},
AddressInformation{Phone, Address},
ContactInformation{Email, Phone}
]
openapi: 3.0.0
info:
version: 1.0.0
title: 'INPUT-FORM-API'
paths:
/api/v1/test/healthcheck:
get:
summary: Health check for the test api services. Used Internally
operationId: Externalhealthcheck
description: healthcheck for the test services status.
responses:
'200':
description: This status is always returned when service is Ok.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthcheckObject'
/api/v1/test/newformentry:
post:
summary: End Point to insert data into the new table.
operationId: NewFormEntry
description: EndPoint to insert data for new form.
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/NewFormEntry'
responses:
'200':
description: This status is always returned when service is Ok.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthcheckObject'
components:
schemas:
NewFormEntry:
$ref: '#/components/schemas/UserInformation'
$ref: '#/components/schemas/AddressInformation'
$ref: '#/components/schemas/ContactInformation'
$ref: '#/components/schemas/MessageFromBene'
UserInformation:
required:
- FirstName
- LastName
properties:
FirstName:
type: string
LastName:
type: string
AddressInformation:
required:
- StreetAddress
- City
- State
- ZipCode
properties:
StreetAddress:
type: string
StreetAddress2:
type: string
City:
type: string
State:
type: string
ZipCode:
type: integer
format: int64
ContactInformation:
required:
- PhoneNumber
- Email
properties:
PhoneNumber:
type: integer
format: int64
maximum: 9
Email:
type: string
HomePhone:
type: integer
format: int64
maximum: 9
Cell:
type: integer
format: int64
maximum: 9
WorkPhone:
type: integer
format: int64
maximum: 9
MessageFromBene:
required:
- Message
properties:
PhoneNumber:
type: integer
format: int64
maximum: 9
Message:
type: string
HealthcheckObject:
required:
- Status
- ErrorMessage
properties:
Status:
type: string
ErrorMessage:
type: string
So the NewFormEntry schema must be an array containing 3 objects, where the 1st object must be UserInformation, the second object must be AddressInformation, and the 3rd object mube be ContactInformation. This is like a tuple, i.e. an ordered sequence of elements where each element has a specfic type. Tuple definitions are slightly different in different OpenAPI versions.
OpenAPI 3.1
If or when you migrate to OAS 3.1, such an array can be defined using prefixItems. This keyword specifies the schema for each element position (in other words, it specifies the order of elements in the array):
components:
schemas:
NewFormEntry:
type: array
prefixItems:
- $ref: '#/components/schemas/UserInformation' # type of the 1st element
- $ref: '#/components/schemas/AddressInformation' # type of the 2nd element
- $ref: '#/components/schemas/ContactInformation' # type of the 3rd element
minItems: 3
maxItems: 3
additionalItems: false # can be omitted if `maxItems: 3` is specified
OpenAPI 3.0
In OAS 3.0, you can define the array length (i.e. 3 items) and the possible types of array items (i.e. each item can be either A, B, or C), but there's no way to define a specific order of objects in the array. So the most you can do is this:
components:
schemas:
NewFormEntry:
type: array
items:
oneOf:
- $ref: '#/components/schemas/UserInformation'
- $ref: '#/components/schemas/AddressInformation'
- $ref: '#/components/schemas/ContactInformation'
minItems: 3
maxItems: 3
Note that this definition allows arbitrary order of objects in the array and also multiple instances of the same object (e.g. [UserInformation, UserInformation, UserInformation]). You might want to implement additional backend validations to verify the desired order of objects in this array.
I'm reading this: OpenAPI 3.0 Tutorial
If I'm looking on one of the examples, there are some things I can't understand
openapi: 3.0.0
info:
version: 1.0.0
title: Simple API
description: A simple API to illustrate OpenAPI concepts
servers:
- url: https://example.io/v1
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
paths:
/artists:
get:
description: Returns a list of artists
parameters:
- name: limit
in: query
description: Limits the number of items on a page
schema:
type: integer
- name: offset
in: query
description: Specifies the page number of the artists to be displayed
schema:
type: integer
responses:
'200':
description: Successfully returned a list of artists
content:
application/json:
schema:
type: array
items:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ----- Added lines ----------------------------------------
post:
description: Lets a user post a new artist
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
properties:
artist_name:
type: string
artist_genre:
type: string
albums_recorded:
type: integer
username:
type: string
responses:
'200':
description: Successfully created a new artist
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
message:
type: string
# ---- /Added lines ----------------------------------------
Why the response of /get contains: required: username ? what is the meaning of this ?
if I don't want basic authentication, can I remove this line ?
Why do we need to write required: true for the requestBody under the post ? It's not basic that post contains body ?
The answer of your questions are:
Why the response of /get contains: required: username? what is the meaning of this? if I don't want basic authentication, can I remove this line?
Ans: Username is required means it's mandatory, i.e. response must contain this field with some value in it. It's not associated with basic authentication. So, yes you can remove that line if it is not used by the application.
Why do we need to write required: true for the requestBody under the post? It's not basic that post contains body?
Ans: Required: true is not mandatory to write here. It's an optional field and post must have a request body. Yeah, you are right. It's a basic thing that posts must have to contain the request body.
If you can have any confusion further then let me know. Thanks
I defined in swagger editor the following object(amountInCurrency):
pot:
type: object
properties:
potId:
type: string
name:
type: string
amount:
type: number
status:
type: string
lastChangeTimestamp:
type: string
amountInCurrency:
type: object
items:
$ref: '#/definitions/amountInCurrency'
and
amountInCurrency:
type: object
properties:
currency:
type: string
amount:
type: number
I got in that items currency and amount. however on swagger visualization i see amountInCurrency as an empty map. any idea why?
i would expect to see the currency and amount fields describe in it
-- edit:
if I change the AmountInCurrency type from object to array I do see the internal docs within the doc
doing this:
amountInCurrency:
type: array
items:
$ref: '#/definitions/amountInCurrency'
The amountInCurrency property definition does not look right - it mixes type: object with an array-specific keyword items.
If the amountInCurrency property is an array of amountInCurrency objects, use type: array instead:
amountInCurrency:
type: array # <-----
items:
$ref: '#/definitions/amountInCurrency'
If the amountInCurrency property is an object (an instance of the amountInCurrency object), use $ref like so:
amountInCurrency:
$ref: '#/definitions/amountInCurrency'
I use OpenAPI 3.0.0 and want to pass an array of Items as a parameter in the requestBody. My API definition looks like this:
post:
tags:
- test
summary: Test dummy
operationId: requestBodyTests
requestBody:
description: test the body
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Items'
components:
schemas:
Items:
type: array
items:
$ref: '#/components/schemas/Item'
examples:
- id: bla
text: blubb
- id: bla
text: blubb
Item:
type: object
properties:
id:
type: string
name:
type: string
Swagger UI displays the request body example as follows:
and the request body schema as follows:
Why does it show an orderedmap instead of my normal objects?
Can someone tell me how to do the spec right for having the array with items correct?
Examples inside schemas use the example keyword (singular), not examples (plural).
Also, your YAML indentation is wrong - Items and Item must be indented under schemas, list items in the example must have the same indent, etc. If you paste your spec into http://editor.swagger.io, it will point out syntax errors.
Here's the fixed version:
components:
schemas:
Items:
type: array
items:
$ref: '#/components/schemas/Item'
example: # <------
- id: bla
text: blubb
- id: bla
text: blubb
Item:
type: object
properties:
id:
type: string
name:
type: string
Moreover, you get an example as 'orderedmap' because the example field is A free-form property.
But represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. (OpenAPI spec)
We can write an example as 'string' in both ways:
1.
example: '[ currency: USD, amount: 123 ]'
example: |
[
currency: USD,
amount: 123
]
I have an object that has a property that is an object whose type would be one of list of types. All my attempts have been rejected by Swagger Editor with the following error:
Data does not match any schemas from 'anyOf'
Jump to line 43
Details
Object
code: "ANY_OF_MISSING"
message: "Data does not match any schemas from 'anyOf'"
path: Array [7]
inner: Array [2]
level: 900
type: "Swagger Error"
description: "Data does not match any schemas from 'anyOf'"
lineNumber: 43
The full swagger specification file is as follows (the field in question is DataSetsInquiryRsp.dataSets.dataSet):
swagger: '2.0'
info:
title: My API
description: My Awesome API
version: 1.0.0
paths:
/dataSetsInquiry:
get:
description: Retrieve one or more data-sets.
parameters:
- name: ids
in: query
description: List of identifiers of requested data-sets.
required: true
type: array
items:
type: string
responses:
'200':
description: Requested data-sets.
schema:
$ref: '#/definitions/DataSetsInquiryRsp'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
definitions:
DataSetsInquiryRsp:
type: object
additionalProperties: false
properties:
sessionIdentifier:
description: Identifier of the secure session with the server.
type: number
dataSets:
type: object
additionalProperties: false
properties:
id:
type: string
dataSet:
type: array
items:
oneOf:
- $ref: '#/definitions/Customer'
- $ref: '#/definitions/Merchant'
Customer:
type: object
additionalProperties: false
properties:
firstName:
description: First name of the customer
type: string
lastName:
description: Last name of the customer
type: string
Merchant:
type: object
additionalProperties: false
properties:
code:
description: Code the Merchant.
type: string
name:
description: Name of the Merchant.
type: string
Well, the issue is simply the fact that Swagger doesn't support oneOff. In fact, Swagger supports a subset of Json-Schema and add a few things (datatype file for instance).
What is bad here is the error returned by Swagger. It doesn't help match. And this is the case of all Json-Schema validators I have worked with so far: is-my-json-valid, jsen.