In Swagger 2.0 (OpenAPI spec) is there any way to specify an "example" for a request body and also specify the ref? I can do so for a response body. My case is for a certain PUT the body is a ref, but the instance you'd put would differ from the schema's example value.
- name: myObj
in: body
description: The information
required: true
schema:
$ref: '#/definitions/SomeObject'
example: 'some string that conforms to my ref'
In OpenAPI 2.0 - no, not really. $ref overwrites any adjacent keywords, so the example will be ignored. Some tools support x-example or x-examples for parameters, so depending on your tool you might be able to use
- name: myObj
in: body
description: The information
required: true
schema:
$ref: '#/definitions/SomeObject'
x-example:
property1: value1
property2: value2
or
- name: myObj
in: body
description: The information
required: true
schema:
$ref: '#/definitions/SomeObject'
x-examples:
application/json:
property1: value1
property2: value2
or something similar.
What you want is possible in OpenAPI 3.0:
openapi: 3.0.0
...
paths:
/something:
put:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SomeObject'
example:
property1: value1
property2: value2
This is supported in Swagger UI 3.17.4 and later.
Related
I want to extend the "200SuccessDefault" response with a schema or example.
paths:
/home:
...
responses:
200:
$ref: '#/components/responses/200SuccessDefault'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PieChartElement'
examples:
PieChart:
$ref: '#/components/examples/PieChart_1'
This approach runs into an error, the schema and examples fields are ignored:
Sibling values alongside $refs are ignored. To add properties to a $ref, wrap the $ref into allOf, or move the extra properties into the referenced definition (if applicable).
I tried allOf:
paths:
/home:
responses:
200:
allOf:
- $ref: '#/components/responses/200SuccessDefault'
- content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PieChartElement'
examples:
PieChart:
$ref: '#/components/examples/PieChart_1'
This approach runs into the error:
should NOT have additional properties additionalProperty: allOf
should have required property 'description' missingProperty: description
You cannot extend a referenced response object. But, you can use a shared schema object and extend it utilizing allOf within schema.
Inside allOf you can put:
your $ref
a new type extending your default response
If you want to give an example of an entire extended response (JSON), just put it into "application/json".
An example of OpenAPI would be:
"202":
description: Extended response sample
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/application"
- type: object
properties:
anotherProperty:
type: string
maxLength: 200
example: "Property example"
example: {id: 1234, anotherProperty: "Hello"}
I am using OpenAPI+OpenAPI-generator with spring boot, and trying to use the schema oneof as follows:
This is the configuration in the requests.yaml file:
...
requestBody:
name: request
required: true
content:
application/json:
schema:
oneOf:
- $ref: 'components.yaml#/Request'
- $ref: 'components.yaml#/ComplexRequest'
...
and this is the relevant configuration in the components.yaml file:
Request:
allOf:
- $ref: '#/BaseInfo'
- type: object
properties:
should_create:
type: boolean
enum: [ false ]
reference_id:
type: string
required:
- reference_id
ComplexRequest:
allOf:
- $ref: '#/BaseInfo'
- type: object
properties:
should_create:
type: boolean
enum: [ true ]
create_data:
$ref: '#/Reference'
required:
- create_data
BaseInfo:
type: object
properties:
customer_id:
type: string
Reference:
type: object
properties:
propery_1:
type: string
propery_2:
type: string
propery_3:
type: string
For some reason, all of these components and only these are not being generated.
Can someone enlighten me on what am I doing wrong here?
If someone is facing this issue, I hope I'll save you some investigation time;
As for March 2022, it seems like oneOf (and anyOf) is just not supported by openapi-generator:
https://openapi-generator.tech/docs/roadmap/#short-term
And though not compatible for my situation, you can try the solutions suggested here:
How to use OpenAPI "oneOf" property with openapi-generator-maven-plugin when generating Spring code
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'm using SwaggerHub with OpenAPI 3 to define an API. One route GET /foo/{id], should return the foo object of a given id, with its associated bar objects. The API will return something like: {id: 4, name: 'test', bars: [{id: 53, name: 'barName1'}, {id: 87, name: 'barName2'}]}. I.e. there is a many-to-many relationship between foo and bar.
How do I describe this in OpenAPI 3 syntax? I have tried using the anyOf property. So far I have:
paths:
/foo/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Foo'
anyOf:
- $ref: '#/components/schemas/Bar'
But this doesn't appear to show the correct schema in the UI (there is no mention of Bar in the UI).
You don't need anyOf. anyOf indicates an alternative ("either Foo or Bar"), whereas you have a usual nested structure - an object Foo with the property bars that is an array of Bars. This can be described as:
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Foo'
components:
schemas:
Foo:
type: object
properties:
bars:
type: array
items:
$ref: '#/components/schemas/Bar'
required:
- bars
Bar:
...
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
]