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.
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.
I'm uising swagger-ui with OpenApi 3.0.2 spec.
I set a requestBody with multipart/form-data content.
Everithing works fine when I execute the request from swagger-ui but...
If I add a parameter of type array, it will be transformed in curl call in this way:
-F "tags=my,tag"
I need the array to be exploded
-F 'tags[]=my' \
-F 'tags[]=tag'
I look at the documentation and find some style and explode properties, but they only works on parameters attribute, not on requestBody (?).
In my route file:
post:
tags:
- media-image
summary: Create a media image
requestBody:
description: A JSON object containing media image information
required: true
content:
multipart/form-data:
schema:
allOf:
- $ref: '../schemas/media-image-fillable.yaml'
- required:
- title
- back_office_title
- alt
- file
The media-image-fillable.yaml
type: object
allOf:
- $ref: './media-image-base.yaml'
- properties:
file:
type: string
format: binary
tags:
type: array
items:
type: string
and the media-image-base.yaml
type: object
properties:
title:
type: string
back_office_title:
type: string
description:
type: string
alt:
type: string
Ok, I found the solution.
I only had to rename tags property in tags[], now it works.
I am writing API documentation using OpenAPI 3.0. At the moment I have:
paths:
/script/update:
post:
tags:
- "Script"
summary: Update a script
operationId: updateScript
responses:
'200':
description: OK
"404":
description: Not Found
requestBody:
description: A script object in order to make the request
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
subsite_id:
type: string
script:
type: object
properties:
script:
$ref: '#/components/schemas/ScriptType'
type:
type: string
enum:
- custom
- interface
- freshbot
- feeder
- getter
- smcf
status:
$ref: '#/components/schemas/ScriptStatus'
comment:
type: string
format: string
reason:
type: string
format: string
To problem comes when I try to use to Swagger UI.
The only thing that appears is the following:
What I want is that the script object can be filled out field by field for each of the properties it has, like the subsite_id. What am I missing?
Swagger UI 3.x and 4.x do not have a form editor for JSON objects, so all JSON data needs to be entered in the JSON format: { "prop": value, ... }
Here's the corresponding feature request you can track:
https://github.com/swagger-api/swagger-ui/issues/2771
I am having problem with my OpenAPI spec file. I am trying to call an exposed url to 'GET' an id but every time i port forward the service to my local and then try to send request through API document my connection is refused. I would appreciate any help. The id that i am expecting would be in JSON format. Below is my spec file
openapi: "3.0.0"
info:
version: 1.0.0
title: Id Generator
servers:
url: www.someurl.com
paths:
/posts:
get:
summary: Get Id
operationId: id
tags:
- posts
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: "#/definition/Post"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/definition/Error"
definition:
Post:
type: object
properties:
id:
type: string
Error:
properties:
id:
type: string
As of June 21 2017, OpenAPI Specification 3.0 is not out yet and Swagger UI does not support OpenAPI 3.0 yet, so your example can't possibly work. Keep an eye on Swagger UI releases page to know when support for OpenAPI 3.0 is available.
Also, you'll need to fix the errors in your spec to make it a valid OpenAPI 3.0 spec:
servers is an array, so change that to:
servers:
- url: http://www.someurl.com
Response status codes must be quoted: "200" or '200'.
Indent the $ref under schemas:
schema:
$ref: "#/definition/Post"
...
schema:
$ref: "#/definition/Error"
Change definition to components->schemas and fix the indentation for Post:
components:
schemas:
Post:
type: object
properties:
id:
type: string
Error:
properties:
id:
type: string
I have a service that can have two different kind of body parameters based on the Content-Type header.
E.g. for path /Pet:
If Content-Type: application/somecustom.resource+json is used, then POST can take up Pet as the body parameter.
If Content-Type: application/somecustom.function+json is used, then POST should take up some different body parameter to invoke a function and return a different response.
Any suggestion on how to manifest this in OpenAPI (Swagger)?
OpenAPI 3.0 supports different schemas per media type.
openapi: 3.0.0
...
paths:
/pet:
post:
requestBody:
required: true
content:
application/somecustom.resource+json:
schema:
$ref: '#/components/schemas/Pet'
application/somecustom.function+json:
schema:
$ref: '#/components/schemas/Foo'
No, it's not possible to define a two different body parameters for the same operation, in the same path item. The path item name are unique by virtue of being property names (and therefore "keys" in the JSON key-value map), and Swagger specification allows at most one body parameter in a given operation.
There are a few alternative approaches to address this need:
Create two separate path items
For example:
/pets/createFromDescription:
post:
summary: Create a pet from a basic description
operationId: createPetFromDescription
parameters:
- name: petDescription
in: body
required: true
schema:
$ref: "#/definitions/PetDescriptionObject"
responses:
200:
description: OK
/pets/createFromCatalog:
post:
summary: Create a pet from a standard catalog entry
operationId: createPetFromCatalogEntry
parameters:
- name: petCatalogEntry
in: body
required: true
schema:
$ref: "#/definitions/PetCatalogEntry"
responses:
200:
description: OK
Create subtypes, with a discriminator
Described in the Swagger–OpenAPI 2.0 specification here.
Example:
/pets:
post:
summary: Create a pet
operationId: createPet
parameters:
- name: petSource
in: body
description: Structured pet information, from which to create the object
required: true
schema:
$ref: "#/definitions/CreatePet_Request"
responses:
200:
description: OK
definitions:
CreatePet_Request:
type: object
properties:
requestVariant:
type: string
required:
- requestVariant
discriminator: requestVariant
PetDescriptionObject:
allOf:
- $ref: "#/definitions/CreatePet_Request"
- type: object
properties:
name:
type: string
description:
type: string
PetCatalogEntry:
allOf:
- $ref: "#/definitions/CreatePet_Request"
- type: object
properties:
SKU:
type: string
Breed:
type: string
Comments:
type: string
Neither of these methods is keyed to the media type of the request. While your request may accept multiple media types, if the use of a particular media type implies some requirement about the request body, you'd have to document that in the description property of the operation or body parameter.