Swagger's allOf shows up as undefined - rest

I've take the allOf examples in https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#models-with-composition, and applied them to parameters schema and responses schema. My allOf parameters and responses, however, show as undefined. When just using Pet instead of Cat, it works fine. Please let me know how to use Swagger's allOf
swagger: '2.0'
# This is your document metadata
info:
version: "0.0.0"
title: <enter your title>
# Describe your paths here
paths:
/test1:
# This is a HTTP operation
post:
description: bla bla
parameters:
- name: Pet
required: true
in: body
description: The Pet.
schema:
$ref: '#/definitions/Pet'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/Pet'
/test2:
# This is a HTTP operation
post:
description: bla bla
parameters:
- name: Cat
required: true
in: body
description: The cat.
schema:
$ref: '#/definitions/Cat'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/Cat'
definitions:
Pet:
type: object
discriminator: petType
properties:
name:
type: string
petType:
type: string
required:
- name
- petType
Cat:
description: A representation of a cat
allOf:
- $ref: '#/definitions/Pet'
- type: object
properties:
huntingSkill:
type: string
description: The measured skill for hunting
default: lazy
enum:
- clueless
- lazy
- adventurous
- aggressive
required:
- huntingSkill

A type field is missing in Cat Definitions Object and therefore swagger-editor shows undefined.
Add type: object as follow can fix it:
Cat:
type: object
description: A representation of a cat
allOf:

Related

Redoc-cli discriminator

I have redoc-cli installed via npm
$ redoc-cli --version
0.13.20
Now I use it to build docs with the following
openapi: 3.1.0
info:
title: Sample API
version: '1.0'
contact:
email: some#email.com
description: Api description.
tags:
- name: sample tag
description: tag description
servers:
- url: http://localhost:3000
paths:
/int/methods/list:
post:
summary: Sample op
operationId: sample-op
description: Op description.
requestBody:
content:
application/json:
schema:
type: object
properties:
test:
$ref: '#/components/schemas/test'
tags:
- sample tag
components:
schemas:
test1:
title: Test
type: object
properties:
testType:
type: string
testOne:
type: string
test2:
title: Test 2
type: object
properties:
testType:
type: string
testTwo:
type: number
test:
title: Test Polymorph
oneOf:
- $ref: '#/components/schemas/test1'
- $ref: '#/components/schemas/test2'
discriminator:
propertyName: testType
mapping:
ONE: '#/components/schemas/test1'
TWO: '#/components/schemas/test2'
Still attempting to
$ redoc-cli build 04_interface/test.yaml
Prerendering docs
🎉 bundled successfully in: redoc-static.html (1061 KiB) [⏱ 0.179s]
Gives me a result as-if the whole discriminator was missing, i.e.
...instaed of the expected select box, as documented in redocly
I know redocly and redoc-cli are not the same, but redoc-cli used to support discriminators in the past, just at some point it seems to me that it stopped working - or there is some syntax niche I am missing.
So i found what the turning point is. Look at this example.
openapi: 3.1.0
info:
title: Sample API
version: '1.0'
contact:
email: some#email.com
description: Api description.
tags:
- name: sample tag
description: tag description
servers:
- url: http://localhost:3000
paths:
/sample-path:
post:
summary: Sample op
operationId: sample-op
description: Op description.
requestBody:
content:
application/json:
schema:
title: Test
type: object
properties:
prop1:
title: Test Polymorph
oneOf:
- $ref: '#/components/schemas/test1'
- $ref: '#/components/schemas/test2'
discriminator:
propertyName: testType
mapping:
ONE: '#/components/schemas/test1'
TWO: '#/components/schemas/test2'
prop2:
$ref: '#/components/schemas/testPolymorph'
tags:
- sample tag
/another-path:
post:
summary: Another op
operationId: another-op
description: Another op description.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/testPolymorph'
tags:
- sample tag
components:
schemas:
test1:
title: Test - Variant 1
type: object
properties:
testType:
type: string
testOne:
type: string
test2:
title: Test Variant 2
type: object
properties:
testType:
type: string
testTwo:
type: number
testPolymorph:
title: Test Polymorph
discriminator:
propertyName: testType
mapping:
ONE: '#/components/schemas/test1'
TWO: '#/components/schemas/test2'
oneOf:
- $ref: '#/components/schemas/test1'
- $ref: '#/components/schemas/test2'
This specs yields the following visualization
It seems the discriminator doesnt work for $refs, only if the $ref is on the top schema level.
I started an issue here https://github.com/Redocly/redoc/issues/2252

OpenAPI models with multiple discriminators not showing in Redocly

I'm trying to use OpenAPI v3 to define models with polymorphism. I've tried the following model definitions and, while they appear to be successfully processed by the Redocly linter, the API documentation generated by Redocly seems to fail to properly document the models.
Here are the OpenAPI document:
openapi: 3.0.3
info:
version: 0.0.3-SNAPSHOT
title: Pet Adaption API
description: |
Adopt a pet!
servers:
- url: 'https://example/pet/api/v1'
description: Pet Adaption API
paths:
/pet_adaptions:
post:
summary: Mark a pet for adaption
description: Mark a pet for adaption
operationId: adopt
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetType'
required: true
responses:
200:
description: The pet was marked for adaption
400:
description: The payload was poorly formatted.
500:
description: Unexpected server error.
components:
schemas:
Pet:
type: object
required:
- name
properties:
name:
type: string
description: What goes on their collar.
PetType:
type: object
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
discriminator:
propertyName: type
mapping:
CAT: '#/components/schemas/Cat'
DOG: '#/components/schemas/Dog'
Dog:
type: object
oneOf:
- $ref: '#/components/schemas/LargeDog'
- $ref: '#/components/schemas/SmallDog'
discriminator:
propertyName: size
mapping:
large: '#/components/schemas/LargeDog'
small: '#/components/schemas/SmallDog'
required:
- type
properties:
type:
type: string
description: The type of pet. Always set to `DOG`
LargeDog:
type: object
allOf:
- $ref: '#/components/schemas/Pet'
required:
- size
- floofFactor
properties:
size:
type: string
description: The size of dog. Always set to `large`
floofFactor:
type: integer
description: Floofiness of large dog (1 - 10)
SmallDog:
type: object
allOf:
- $ref: '#/components/schemas/Pet'
required:
- type
- size
- yapFactor
properties:
type:
type: string
description: The type of pet. Always set to `DOG`
size:
type: string
description: The size of dog. Always set to `small`
yapFactor:
type: number
description: Yapiness of small dog (0 - 1.0)
Cat:
type: object
allOf:
- $ref: '#/components/schemas/Pet'
required:
- type
- colour
properties:
type:
type: string
description: The type of pet. Always set to `CAT`
colour:
type: string
description: Colour if the cat's coat
And the following should all be valid examples:
LargeDog
{
"name": "Rex",
"type": "DOG",
"size": "large",
"floofFactor": 3
}
SmallDog
{
"name": "Skip",
"type": "DOG",
"size": "small",
"yapFactor": 0.9
}
Cat
{
"name": "Mr Tinkles",
"type": "CAT",
"colour": "black"
}
The API documentation renders just fine if looking at the CAT example but not when looking at the DOG example.
Have I created an invalid OpenAPI v3 document or is this likely just an issue with Redocly?
Try to pass the discriminator inside size property.
Dog:
type: object
required:
- type
properties:
type:
type: string
description: The type of pet. Always set to `DOG`
size:
type: string
description: The type of pet. Always set to `DOG`
discriminator:
propertyName: size
mapping:
large: '#/components/schemas/LargeDog'
small: '#/components/schemas/SmallDog'
oneOf:
- $ref: '#/components/schemas/LargeDog'
- $ref: '#/components/schemas/SmallDog'
enter image description here

How can I inline example field in OpenAPI spec?

I've got an OpenAPI schema (edited it to be a minimal working example):
---
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/Player'
- type: object
required:
- id
properties:
spec:
type: object
required:
- display_name
components:
schemas:
Player:
type: object
properties:
spec:
$ref: '#/components/schemas/PlayerSpec'
additionalProperties: false
PlayerSpec:
type: object
properties:
display_name:
type: string
description: The name of the player.
example: LeBron
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
additionalProperties: false
PlayerReference:
type: object
required:
- id
properties:
id:
type: string
example: 'lebron-23'
and after I run: redoc-cli bundle example.yaml to generate the docs I can see:
(basically id: lebron-23 is there -- i.e., the docs look as expected).
The problem is in order to make it work I had to add example: 'lebron-23' to the definition of a generic PlayerReference component but I'd rather move this example: 'lebron-23' line to this section instead:
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
<-------- add id.example here or something
Since environment is an object, an object-level example would look like this:
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
example:
id: lebron-23
This example will probably override any examples from allOf subschemas (rather than merge with them), so make sure to include all property values you want to see in this example.

Multi return type with different headers in OpenAPI3

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.)

Semantic swagger error for a path parameter

I am new to Swagger, and I have being fixing some errors I got after importing the .json file into https://editor.swagger.io/ but I am getting this error.
Declared path parameter "PARAMETER" needs to be defined within every
operation in the path (missing in "get"), or moved to the path-level
parameters object
Here is the part that is giving me the error:
'/api/v1/images/{PARAMETER}/{type}':
get:
tags:
- Images
summary: 'summar'
operationId: DownloadFIle
consumes: []
produces:
- application/json
parameters:
- name: PARAMETER
in: path
required: true
type: string
- name: type
in: path
required: true
type: string
responses:
'200':
description: Success
schema:
uniqueItems: false
type: array
items:
$ref: '#/definitions/CloudImageInfo'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
type: string
'404':
description: Not Found
schema:
type: string
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
post:
tags:
- Images
summary: summary
description: " description"
operationId: UploadFile
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: imageFiles
in: formData
required: false
type: array
items: {}
collectionFormat: multi
uniqueItems: false
- name: PARAMETER
in: path
required: true
type: string
- name: type
in: path
required: true
type: string
responses:
'201':
description: Success
schema:
uniqueItems: false
type: array
items:
$ref: '#/definitions/CloudImageInfo'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
type: string
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
can anyone point me where to look or what can I fix?