I am using http://editor.swagger.io minimal.yaml example to define a MenuItem which has submenuitem property of type array recursively referencing MenuItem. But I get submenuitem as undefined. Any pointers to what might be wrong ?
---
swagger: '2.0'
info:
version: 0.0.0
title: Simple API
paths:
/:
get:
responses:
200:
description: OK
definitions:
MenuItem:
properties:
submenuitem:
items:
$ref: "#/definitions/MenuItem"
title: SubMenuItem
type: array
display_name:
minLength: 2
title: "Link display name"
type: string
Related
Consider this OAS3 spec (testMinMax3.yaml):
openapi: 3.0.1
info:
title: OpenAPI Test
description: Test
license:
name: Apache-2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
servers:
- url: http://localhost:9999/v2
paths:
/ping:
post:
summary: test
description: test it
operationId: pingOp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SomeObj'
required: true
responses:
200:
description: OK
content: {}
components:
schemas:
SomeObj:
type: string
minLength: 1
maxLength: 3
Does non-empty (aka minLength: 1) implies required even if a field is not set based on the openapi spec (1)? Or does that apply only if a value for the field is provided by the user (2)?
No.
minLength and required are separate constraints. minLength means that if a string value is provided, its length must be minLength or more.
The following YAML:
openapi: 3.0.0
info:
title: test
version: 1.0.0
paths:
/test:
get:
summary: test
responses:
'200':
description: Test
content:
application/json:
schema:
oneOf:
- allOf:
- type: object
properties:
firstA:
type: string
- type: object
properties:
firstB:
type: string
- allOf:
- type: object
properties:
secondA:
type: string
- type: object
properties:
secondB:
type: string
Does not render at all in the swagger editor.
In ReDoc it also fails to render properly:
If nesting multiple allOf instances directly inside of oneOf is invalid, how could I achieve the same result with a valid spec?
ReDoc author here.
It is a ReDoc bug. Your spec is valid.
It has been already fixed and will be available in 2.0.0-alpha.40.
I have a model defined as:
Event:
type: object
properties:
id:
type: string
timestamp:
type: string
format: date-time
type:
type: string
enum:
- click
- open
- sent
click:
type: object
properties:
url:
type: string
title:
type: string
open:
type: object
properties:
subject:
type: string
sent:
type: object
properties:
subject:
type: string
from:
type: string
to:
type: string
However, the shape is actually different depending on the value of the type enum field. It can be one of three, I tried to define the differences in the examples (see below) but this did not work.
As you can see, the below shows three examples, each one is different depending on the type. This is how the API behaves, but it is not straightforward to document this expected behaviour.
examples:
application/json:
- id: >
ad1b12f0-63a8-47b5-9820-3e447143ce7e
timestamp: >
2017-09-29T16:45:20.000+00:00
type: click
click:
url: >
www.some-website-somewhere.org/12345
title: >
Click here!
- id: >
d9e787fa-db49-4bd8-97c3-df45f159295c
timestamp: >
2017-09-29T16:45:20.000+00:00
type: open
open:
subject: >
Have you seen this?
- id: >
30adc194-0f5f-4889-abd4-4fa964d0bb42
timestamp: >
2017-09-29T16:45:20.000+00:00
type: sent
sent:
subject: >
Have you seen this?
from: >
bill#office.gov
to: >
mon#gmail.com
I read a few places that mention this is not possible, but I am hoping to get some "outside the box" thinkers to help me find a solution.
This is possible using model inheritance/composition and discriminator.
First, define the base model Event that contains just the common properties, and mark the type property as discriminator:
definitions:
Event:
type: object
discriminator: type
required:
- type # discriminator property is required
properties:
id:
type: string
example: ad1b12f0-63a8-47b5-9820-3e447143ce7e
timestamp:
type: string
format: date-time
example: 2017-09-29T16:45:20.000+00:00
type:
type: string
enum:
- click
- open
- sent
Then inherit the click/open/sent models from the base Event model via allOf. The names of the child models must be the same as the values of the discriminator property. In your example, the models must be named click, open and sent. If you use Swagger UI, you can add title to override the displayed model names.
click:
title: ClickEvent
allOf:
- $ref: '#/definitions/Event'
- type: object
properties:
click:
type: object
properties:
url:
type: string
example: www.some-website-somewhere.org/12345
title:
type: string
example: Click here!
In operations, use the base model (Event) as the request or response schema:
responses:
200:
description: OK
schema:
$ref: '#/definitions/Event'
The clients should examine the value of the discriminator property (in this example - type) to decide which inherited model to use.
Note for Swagger UI users: Swagger UI and Swagger Editor currently do not support switching models based on discriminator. Follow this issue for updates.
In OpenAPI 3.0 it's easier - you can simply use oneOf to define alternate schemas for a request or response.
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ClickEvent'
- $ref: '#/components/schemas/OpenEvent'
- $ref: '#/components/schemas/SentEvent'
# Optional mapping of `type` values to models
discriminator:
propertyName: type
mapping:
click: '#/components/schemas/ClickEvent'
open: '#/components/schemas/OpenEvent'
sent: '#/components/schemas/SentEvent'
I'm trying to write a simple Swagger / Open API definition using the Swagger Editor.
swagger: "2.0"
info:
version: 1.0.0
title: Test API
description: Test API
schemes:
- https
host: hipaa.ai
basePath: /v1
paths:
/comments:
post:
summary: Your comments
description: Comments
parameters:
- name: text
in: body
description: An array of text strings
type: array
minItems: 1
maxItems: 1000
items:
type: text
I'm getting the following error:
Schema error at paths./comments.post.parameters[0]
is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>
I've checked the Swagger schema reference, and the petstore example, but I'm not sure why I'm getting this. Any ideas?
Body parameters use the schema keyword to specify the type, so you need to move type, items, minItems and maxItems under schema.
Also, type: text is not a valid type. Use type: string instead.
parameters:
- name: text
in: body
description: An array of text strings
schema:
type: array
minItems: 1
maxItems: 1000
items:
type: string
is it possible to have an array of complex object inside the get parameters?
If I try this code, I get a parameter definition error due to this line: $refs: '#/definitions/pax'
swagger: '2.0'
info:
version: 0.0.0
title: Simple API
paths:
/:
get:
parameters:
- name: passengers
in: query
type: array
items:
$refs: '#/definitions/pax'
responses:
200:
description: TODO
definitions:
pax:
type: object
properties:
name:
type: string
familyname:
type: string
For request parameters, only body parameter can be defined with an Object (model).
You will need to provide an example of the URL query string so that we can help you define it with Swagger/OpenAPI spec.