I have the following definitions in my Swagger file (according to the Swagger Specification):
definitions:
ErrorItem:
type: object
properties:
code:
type: string
message:
type: string
field:
type: string
description: field
Error:
description: "List of errors"
type: array
items:
$ref: '#/definitions/ErrorItem'
but in the Swagger Editor I see the following:
Is this correct? The Errors array should not visually have anything else in Models section?
This was a bug introduced in Swagger Editor v.3.2.0 which was fixed in v.3.2.4,
and also fixed in the online http://editor.swagger.io.
Related
I've been struggling with an issue in an openapi 3.0.1 spec json document I've been working on.
The issue I'm seeing in the online swagger editor (editor.swagger.io) is very strange where the Request body Example Value section of a POST does not show the "layers", which is an array defined within my MixBase schema component, based on the MixLayer schema component. The MixLayer schema component has an array of MixLayerComponent schema components.
However, if I include a $ref to the MixBase schema in the responses section, all the elements are shown correctly.
Request body Example Value section that is missing the 'layers':
{
"mixId": "4f8b533f-7449-4056-92ff-11b1de94d656",
"mixDescription": "SES5M",
"mixScaleName": "MyScale",
"mixRoom": "MixingRoomABC",
"mixProgramId": "ABC-123-ProgramId",
"mixDateTime": "2018-06-07T12:51:25.077Z",
"mixState": "Paused",
"mixNumber": "131",
"mixedByUserName": "john.smith#example.com",
"mixedByFirstName": "John",
"mixedByLastName": "Smith"
}
Responses Example Value section returning the correct list of elements including 'layers':
{
"mixId": "4f8b533f-7449-4056-92ff-11b1de94d656",
"mixDescription": "SES5M",
"mixScaleName": "MyScale",
"mixRoom": "MixingRoomABC",
"mixProgramId": "ABC-123-ProgramId",
"mixDateTime": "2018-06-07T12:51:25.077Z",
"mixState": "Paused",
"mixNumber": "131",
"mixedByUserName": "john.smith#example.com",
"mixedByFirstName": "John",
"mixedByLastName": "Smith",
"layers": [ -- this represents the MixLayer component
{
"unitOfMeasure": "g",
"Components": [ -- this represents the MixLayerComponent correctly
{
"code": "800C",
"description": "800C",
"poured": 204.5,
"density": 1.041
}
]
}
]
}
My requestBody section is defined as: (doesn't show 'layers')
requestBody:
required: true
description: Paint mix information to create
content:
application/json:
schema:
$ref: '#/components/schemas/MixBase'
My responses section is defined as: (and this displays correctly in the Response examples section)
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/MixBase'
Here is the definition of the 'layers' within the MixBase schema component (which is the last element in the MixBase definition which is why additionalProperties is set to false): (The formatting might not be correct in stack overflow but the swagger editor doesn't complain so I don't believe the issue is linked to formatting)
layers:
description: Layer related information for components of the mix
type: array
items:
$ref: '#/components/schemas/MixLayer'
readOnly: true
additionalProperties: false
Here is the definition of the MixLayer:
MixLayer:
required:
- Components
type: object
properties:
unitOfMeasure:
description: Unit of volume for the components of the layer
maxLength: 10
type: string
nullable: true
example: g
Components:
description: The components that make up the layer in the mix
type: array
items:
$ref: '#/components/schemas/MixLayerComponent'
readOnly: true
additionalProperties: false
Here is the definition of the MixLayerComponent:
MixLayerComponent:
required:
- code
- density
- poured
type: object
properties:
code:
description: The code associated with the mix component of the layer
maxLength: 25
minLength: 1
type: string
example: 800C
description:
description: The description of the mix component of the layer
maxLength: 120
type: string
nullable: true
example: 800C
poured:
description: >-
The quantity, expressed in the unit of measurement, consumed for the
mix component
type: number
format: double
example: 204.5
density:
description: The density associated with the mix component of the layer
type: number
format: double
example: 1.041
additionalProperties: false
I thought that the "Components" element in the MixLayer component schema might be a reserved keyword in openapi so I changed the references to something else and it still has the same issue.
I thought this issue might be with the online swagger editor (editor.swagger.io) but the same thing occurs in Postman. I also tried browsers Chrome, Edge, and Firefox and they all
have the same issue. I have also tried an XML content type in addition to the JSON I would like to use but still the same issue.
I don't access to post my openapi.json file on stack overflow but I hope this provides enough information.
Any insights anyone has for me to continue a line of investigation would be greatly appreciated.
Thank you for your time in advance,
Dave
layers is defined as a read-only property (readOnly: true) - that's why it doesn't appear in the request body example.
I'm encountering a really weird bug in swagger.
When trying to render a component with a property called 'entries', the compiler breaks with the error:
The provided definition does not specify a valid version field.
Please indicate a valid Swagger or OpenAPI version field.
Supported version fields are swagger: "2.0" and those that
match openapi: 3.0.n (for example, openapi: 3.0.0).
An example that will return this error:
openapi: 3.0.2
info:
title: API Documentation
version: '1'
paths:
/v1/detail/:
get:
tags:
- clips
summary: Get details
operationId: Create Detail
description: Retrieve details
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/Clip'
description: ''
components:
schemas:
Clip:
type: object
properties:
entries:
type: string
example: 'abc'
But by renaming entries to something else, like 'x_entries', the compiler is OK.
I couldn't find any reference to 'entries' in the openapi documentation, although I could be wrong here. Does anyone know why 'entries' as an property in a component causes an issue?
It was a bug in Swagger UI v. 3.25.3 and Swagger Editor v. 3.8.3.
Fixed in UI v. 3.25.4 and Editor v. 3.9.0.
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'm writing a Swagger definition on swaggerhub. There's an option to share models among multiple Swaggers. After swaggers are complete there's an option to download resolved Swagger with the linked definitions imported.
My problem is that this resolved download adds a example node to the models which for whatever reason overrides every attribute when we copy this new Swagger in editor again.
Suppose we have following sample
---
swagger: "2.0"
info:
description: ""
version: 1.0.0
title: title
host: "example.com"
basePath: /
schemes:
- http
consumes:
- application/json
produces:
- application/json
paths:
/test-service:
post:
tags:
- test-service
operationId: test-service
parameters:
- in: body
name: body
description: body
required: true
schema:
$ref: '#/definitions/A'
responses:
201:
description: success
schema:
$ref: '#/definitions/A'
definitions:
A:
type: object
properties:
a1:
type: string
a2:
type: string
Following is how it's displayed in the Swagger UI,
This is correct way, however when I there's an example node in the model A, only example attributes are displayed in the UI,
Here's the change that that I'm referring to
A:
type: object
properties:
a1:
type: string
a2:
type: string
example:
ex1: Hello
ex2: World
Now, if I import this change in the editor, only attributes ex1 and ex2 and actual attributes a1 and a2 are missing.
Problem is exacerbate when we have inheritance.
What happens is whichever lowest node in hierarchy has example attribute only attributes listed in that are shown in the UI, rather than showing all attributes
Here's a sample wi
Now lets introduce example attribute in C. After addition of example attribute at any level all other attributes are ignored.
Here's the link to example attribute documentation https://swagger.io/docs/specification/2-0/adding-examples/.
There's no description of this weird behavior.
That's how example works. Quoting the OpenAPI 2.0 Specification:
A free-form ... example of an instance for this schema.
That is, example is an example for the entire schema. That's why a schema-level example is displayed as is. It overrides any property-level examples, and won't automatically include properties that aren't included in the example.
In your last example with allOf, the schema for A is equivalent to
definitions:
A:
type: object
properties:
a1:
type: string
a2:
type: string
b1:
type: string
b2:
type: string
c1:
type: string
c2:
type: string
example:
ex1: Hello
ex2: world
which again is why the schema-level example from C overrides everything else.
You might want to use property-level examples instead:
definitions:
A:
type: object
properties:
a1:
type: string
example: Hello # <---
a2:
type: string
example: world # <---
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