I am trying to document an api on swagger (Open api 3.0.x) and I find a problems using $refs.
As written here, it's working as intended, BUT debugger shows an error my request body definition (it lacks content, application/json, schema)
What is the correct way to do this?
/foobarbaz:
post:
requestBody:
description: lorem ipsum
content:
application/json:
schema:
oneOf:
- $ref: '#/components/requestBodies/foo'
- $ref: '#/components/requestBodies/bar'
- $ref: '#/components/requestBodies/baz'
examples:
foo:
$ref: '#/components/examples/foo'
bar:
$ref: '#/components/examples/bar'
baz:
$ref: '#/components/examples/baz'
components:
requestBodies:
foo: <-- here it highlights (Missing property "$ref".)
schema
type: object
properties:
foo:
type: string
bar:
type: string
bar: <-- here it highlights (Missing property "$ref".)
schema
type: object
properties:
foo:
type: string
bar:
type: string
baz: <-- here it highlights (Missing property "$ref".)
schema
type: object
properties:
foo:
type: string
bar:
type: string
examples:
foo:
value:
foo: 'bar'
bar: '20'
bar:
value:
foo: 'bar'
bar: '20'
baz:
value:
foo: 'bar'
bar: '20'
oneOf can only $ref schemas, not requestBody components. Here's the correct version:
/foobarbaz:
post:
requestBody:
description: lorem ipsum
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/foo' # <--- $refs point to schemas, not requestBodies
- $ref: '#/components/schemas/bar'
- $ref: '#/components/schemas/baz'
examples:
...
components:
schemas: # <--- Put the schemas in the "schemas" section rather than "requestBodies"
foo:
type: object
properties:
foo:
type: string
bar:
type: string
bar:
type: object
properties:
foo:
type: string
bar:
type: string
baz:
type: object
properties:
foo:
type: string
bar:
type: string
Related
I've got the following spec:
---
openapi: 3.0.0
info:
title: Players API
version: 0.0.1-alpha1
paths:
/players/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PlayerWrapper'
components:
schemas:
PlayerWrapper:
type: object
properties:
display_name:
type: string
example: 76ers
config:
description: |
The configuration of the player.
example: { spec: { team: 76ers, names: [ 1, 2 ] } }
allOf:
- $ref: '#/components/schemas/Player'
Player:
type: object
properties:
spec:
allOf:
- $ref: '#/components/schemas/BasicPlayer'
additionalProperties: false
BasicPlayer:
type: object
properties:
team:
type: string
names:
allOf:
- $ref: '#/components/schemas/Names'
additionalProperties: false
Names:
type: array
items:
type: string
example: [ Ben, Joel ]
I did verify on Swagger that it's indeed valid. The question is why I can see names: [ 1, 2 ] other than [ Ben, Joel ]. When I do remove that example thing (# example: { spec: { team: 76ers, names: [ 1, 2 ] } }), I can see Ben, Joel example:
Is there a way how I can force override / merge those example? As of now, I feel like my example gets overriden by either of those fields (i.e., either 76ers / [1, 2] or string / [Ben, Joel] but I'd like to get 76ers / [Ben, Joel] instead).
The structure in your schemas isn't quite right. The idea is to provide examples on the simple types (strings, int, etc) and the schema will structure it as required.
So dont put the example on config, put it on the nested simple types like this, ie BasicPlayer object should have the example on team as it's a string:
BasicPlayer:
type: object
properties:
team:
type: string
example: '76ers'
names:
allOf:
- $ref: '#/components/schemas/Names'
Similar with PlayerWrapper.config don't try and give a full object in the example, it gets composed by the member properties. So team gets an example, but Names example is composed from the child type.
PlayerWrapper:
type: object
properties:
display_name:
type: string
example: '76ers'
config:
description: |
The configuration of the player.
allOf:
- $ref: '#/components/schemas/Player'
Which should give you the expected example:
Here's the full swagger:
---
openapi: 3.0.0
info:
title: Players API
version: 0.0.1-alpha1
paths:
/players/{id}:
get:
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PlayerWrapper'
components:
parameters:
id:
name: id
in: path
required: true
schema:
type: string
description: The id.
schemas:
PlayerWrapper:
type: object
properties:
display_name:
type: string
example: '76ers'
config:
description: |
The configuration of the player.
allOf:
- $ref: '#/components/schemas/Player'
Player:
type: object
properties:
spec:
allOf:
- $ref: '#/components/schemas/BasicPlayer'
additionalProperties: false
BasicPlayer:
type: object
properties:
team:
type: string
example: '76ers'
names:
allOf:
- $ref: '#/components/schemas/Names'
additionalProperties: false
Names:
type: array
items:
type: string
example:
- Ben
- Joel
Note it is possible to override schema examples with an example in the resource definition like this:
paths:
/players/{id}:
get:
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PlayerWrapper'
example:
display_name: 76ers
config:
spec:
team: 76ers
names:
- 'Ben'
- 'Joel'
openapi: "3.0.0"
info:
title: project
servers:
- url: http://example1.net/v3
- url: http://example/v3
paths:
/Pn/{PnId}/service1:
post:
summary: Pn data
description: |
can Pn the data
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/dataInfo"
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/dataInfo"
parameters:
- name: PnId
in: path
description: PnId
required: true
schema:
$ref: "#/components/schemas/Pn"
responses:
'200':
description: status
content:
application/json:
schema:
$ref: "#/components/schemas/dataInfoStatus"
example: infoable
default:
description: error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Error:
type: object
properties:
code:
type: integer
message:
type: string
required:
- message
Pn:
type: integer
format: int64
dataInfo:
type: string
dataInfoStatus:
type: string
enum: [infoable, non_infoable,ignorable]
I am sending a single dataInfo in request and getting single dataInfoStatus in response, but I will like to send and array of dataInfo and get an array of dataInfo status.
I tried following:
schema:
type:array
items:
$ref: "#/components/schemas/dataInfo"
but I get
Parser error bad indentation of a mapping entry
for items. I am following this.
How can I achieve sending dataInfo in request as an array of dataInfo and getting in response an array of dataInfoStatus?
You have to add one more space between type: and array, then the error message is gone:
schema:
type: array
items:
$ref: "#/components/schemas/dataInfo"
And you can add the info.version for the version of the openapi file.
I want to write openapi specs for API which will return response as set of object or another object. I am not sure how I can achieve that I have tried many things but when I run codegen for the specs I am getting class OneOfConnectionDTOConnectionPaginatedResponseDTO with error.
I am using below code and I want Set or ConnectionPaginatedResponseDTO in the 200 response
openapi: 3.0.0
servers:
- url: /
info:
title: OIM Manage Connection
version: '1.0'
paths:
'/ManageConnection/viewUserConnection/{oimid}':
get:
tags:
- View Connection
parameters:
- description: OIMID of user
in: path
name: oimid
required: true
schema:
type: string
example: 1234
- description: content type
in: header
name: Content-Type
required: true
schema:
type: string
example: application/json
- description: Start Index of records to be fetched
in: query
name: startIndex
required: false
schema:
type: string
example: 1
- description: Start Index of records to be fetched
in: query
name: count
required: false
schema:
type: string
example: 5
responses:
'200':
description: Connection list returned
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ConnectionDTO'
- $ref: '#/components/schemas/ConnectionPaginatedResponseDTO'
'401':
$ref: '#/components/responses/UnAuthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/DataBaseError'
'501':
$ref: '#/components/responses/MethodError'
components:
responses:
UnAuthorized:
description: Not authorized to access the specified resource
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
MandatoryAttributeNotPassedException:
description: Requested resource can't be accessed
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
Forbidden:
description: Requested resource can't be accessed
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
DataBaseError:
description: Unable to connect to database
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
MethodError:
description: Method not implemented
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
schemas:
ConnectionDTO:
required:
- access_type
- access_identifier
properties:
add_access_date:
type: string
format: date
access_identifier:
type: string
access_type:
type: string
PIN:
type: string
is_primary_access:
type: string
valid_state:
type: string
friendly_name:
type: string
oimid:
type: string
auth_count:
type: string
type: object
ConnectionPaginatedResponseDTO:
properties:
totalResults:
type: integer
itemsPerPage:
type: integer
startIndex:
type: integer
connections:
$ref: '#/components/schemas/ConnectionDTO'
type: object
OIMException:
properties:
errorMessage:
type: array
items:
type: string
message:
type: string
httpStatus:
type: string
code:
type: integer
type: object
I have a data model definition in OpenAPI 3.0, using SwaggerHub to display the UI. I want one of the properties of a model to be related, which is an array of properties of the same model.
Foo:
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/Foo'
The parser doesn't seem to like this - the UI shows the related property as an empty array. Is this kind of self-reference possible in OpenAPI 3.0?
Your definition is correct, it's just Swagger UI currently does not render circular-referenced definitions properly. See issue #3325 for details.
What you can do is add a model example, and Swagger UI will display this example instead of trying to generate an example from the definition.
Foo:
type: object
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/Foo'
example: # <-------
title: foo
related:
- title: bar
- title: baz
related:
- title: qux
Alternatively, you can add an example just for the related array:
Foo:
type: object
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/Foo'
example: # <--- Make sure "example" is on the same level as "type: array"
- title: bar
- title: baz
related:
- title: qux
I got tired of this pesky situation, so I went with no example at all and chose to get rid of the items property, add a description element and use an empty array instead:
Foo:
type: object
properties:
title:
type: string
related:
type: array
description: Array of Foo elements
example: []
You can achieve that by a proxy model:
...
_MessageProxy:
description: Message
type: object
required:
- id
- user
- body
- publishedAt
properties:
id:
title: Message id
type: string
readOnly: true
example: '595f4acf828b0b766ad11290'
user:
$ref: '#/components/schemas/User'
Message:
allOf:
- $ref: '#/components/schemas/_MessageProxy'
- type: object
properties:
parent:
title: Parent
readOnly: true
allOf:
- $ref: '#/components/schemas/_MessageProxy'
...
Using a dummy model and cross reference:
Foo:
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/_Foo'
_Foo:
properties:
title:
type: string
related:
type: array
items:
$ref: '#/components/schemas/Foo'
In the following Swagger definition, I need the parameter labelValue to be of type LabelValueObject, so that it will be validated and correctly deserialized. However, I can't figure out the syntax! How can that be done?
swagger: "2.0"
paths:
/competition:
post:
parameters:
- name: labelValue
in: formData
type: array
items:
type: string ### this has to be a LabelValueObject ###
responses:
default:
description: Error
schema:
$ref: "#/definitions/AnyResponse"
definitions:
AnyResponse:
properties:
any:
type: string
LabelValueObject:
properties:
label:
type: string
value:
type: string
required:
- label
- value
The only way to pass an object as a parameter is to put it in the body (in: body) and then define this object in schema (inline definition or reference to an predefined object with $ref). Here's a full example:
swagger: "2.0"
info:
title: A dummy title
version: 1.0.0
paths:
/competition:
post:
parameters:
- name: labelValue
in: body
schema:
$ref: '#/definitions/LabelValueObject'
responses:
default:
description: Error
schema:
$ref: "#/definitions/AnyResponse"
definitions:
AnyResponse:
properties:
any:
type: string
LabelValueObject:
properties:
label:
type: string
value:
type: string
required:
- label
- value