Greeetings and thanks for your time.
I'm doing some ReDoc documenting using OpenAPI but can't find a way to properly make two levels inheritance. This is kinda what I have:
components:
schemas:
Pet:
type: object
required:
- pet_type
properties:
pet_type:
type: string
discriminator:
propertyName: pet_type
mapping:
dogs: Dog
cats: Cat
Cat:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
# all other properties specific to a `Cat`
properties:
name:
type: string
Dog:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
# all other properties specific to a `Dog`
properties:
bark:
type: string
size:
type: string
discriminator:
propertyName: size
mapping:
large: '#/components/schemas/LargeDog'
medium: '#/components/schemas/MediumDog'
SmallDogs:
allOf:
- $ref: '#/components/schemas/Dog'
- type: object
LargeDogs:
allOf:
- $ref: '#/components/schemas/Dog'
- type: object
Thanks in advance.
You are doing something weird or your example does not fully reveal the essence of the problem. For a dog size, you do not need to use the discriminator. Example below
components:
schemas:
Pet:
type: object
required:
- pet_type
properties:
pet_type:
type: string
discriminator:
propertyName: pet_type
mapping:
dogs: Dog
cats: Cat
Cat:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
# all other properties specific to a `Cat`
properties:
name:
type: string
Dog:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
# all other properties specific to a `Dog`
properties:
bark:
type: string
size:
type: string
enum:
- large
- medium
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
In my Swagger documentation, I have to use same pattern multiple time. Currently, it is placed duplicated.
One thing I improved is that making common parameter (by declaring it inside components). But couldn't find anything to avoid this duplicate pattern between parameters and schemas.
Is there any way, I can use declare this pattern once and re-use it wherever it's needed?
My Swagger looks something like:
openapi: 3.0.3
info:
title: My System
description: Self contained system
version: 1.0.0
servers:
- url: /a/{aId}/
description: Contains the partition
security:
- bearerAuth: []
paths:
"/x/{xId}/y/{yId}/z/{zId}":
get:
x-horizon-permission: "geo.floorplan.read"
tags:
- myTag
operationId: getValue
description: Get Value
parameters:
- name: xId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: yId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: zId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
responses:
"200":
description: OK
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Response'
patch:
tags:
- myTag
operationId: Update
description: Update Data
parameters:
- name: xId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: yId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: zId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Request'
responses:
"200":
description: OK
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Response'
components:
schemas:
Request:
type: object
properties:
data:
type: object
properties:
type:
type: string
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
Response:
type: object
properties:
links:
type: object
properties:
self:
type: string
data:
$ref: '#/components/schemas/Data'
Data:
type: object
properties:
type:
type: string
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
GeometryError:
type: object
required:
- code
- status
- title
properties:
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
status:
type: string
example: 400
title:
type: string
detail:
type: string
meta:
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
Define a schema with this pattern:
components:
schema:
UUID:
type: string
format: uuid # for tools/codegens that have built-in support for UUIDs
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
Then you can reference this schema from other schemas and parameter definitions:
parameters:
- name: xId
in: path
required: true
schema:
$ref: '#/components/schemas/UUID' # <-----
- name: yId
in: path
required: true
schema:
$ref: '#/components/schemas/UUID' # <-----
...
schemas:
Request:
type: object
properties:
data:
type: object
properties:
type:
type: string
id:
$ref: '#/components/schemas/UUID' # <-----
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'
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'
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)