Using OpenAPI 3.0, I need to document how to provide an RFC3339 Date Time JSON input with an HTTP POST to my API endpoint.
The example date-time format will look like this:
"2021-06-20T01:02:03+00:00"
Consulting the Swagger documentation I have tried various methods including the following:
content:
application/json:
schema:
type: object
properties:
datetime:
type: date
pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})T([0-9]{2}):(?:[0-9]{2}):(?:[0-9]{2})+(?:[0-9]{2}):(?:[0-9]{2})/
example: "2021-06-20T01:02:03+00:00"
example: "2021-06-20T01:02:03+00:00"
content:
application/json:
schema:
type: object
properties:
datetime:
type: string
description: RFC3339 Datetime to set
format: date-time
example: "2021-06-20T01:02:03+00:00"
Neither work - an both render the following errors in Swagger UI from the browser:
How do I correctly document this RFC3339 DateTime input in OpenAPI 3.0?
Your second example is correct and is rendered correctly in https://editor.swagger.io - as shown below.
The first example is invalid, it results in a rendering error because the second example keyword (the one alongside datetime) is not expected at this position.
Related
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'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 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.
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
I have a GET route where I would like to encode an object parameter in the url as a query string.
When writing the swagger documentation I basically get errors that disallow me to use schema/object types in a query type parameter:
paths:
/mypath/:
get:
parameters
- in: path
name: someParam
description: some param that works
required: true
type: string
format: timeuuid #good param, works well
- $ref: "#/parameters/mySortingParam" #this yields an error
parameters:
mySortingParam
name: paging
in: query
description: Holds various paging attributes
required: false
schema:
type: object
properties:
pageSize:
type: number
cursor:
type: object
properties:
after:
type: string
format: string
The request query param having an object value would be encoded in an actual request.
Even though swagger shows an error at the top of the screen the object is rendered correctly in the swagger UI editor, however with that error floating on top of the documentation.
I don't think you can use "object" as query parameter in Swagger spec as query parameter only supports primitive type (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types)
This is now possible with OpenAPI 3.0.
parameters:
- in: query
name: values
schema:
type: object
properties:
genre_id:
type: integer
author_id:
type: integer
title:
type: string
example:
{
"genre_id": 1,
"author_id": 1
}
style: form
explode: true
Here you can use style and explode keywords to specify how parameters should be serialised.
style defines how multiple values are delimited. Possible styles depend on the parameter location – path, query, header or cookie.
explode (true/false) specifies whether arrays and objects should
generate separate parameters for each array item or object property.
For the above example the url will be:
https://ebookstore.build/v1/users/books/search?genre_id=1&author_id=1
For more information on describing parameters with OpenAPI v3 and parameter serialisation, please refer here.
This is possible, just not with OpenAPI 2.0. OpenAPI 3.0 describes how this is possible here:
https://swagger.io/docs/specification/describing-parameters/
parameters:
- in: query
name: filter
# Wrap 'schema' into 'content.<media-type>'
content:
application/json: # <---- media type indicates how to serialize / deserialize the parameter content
schema:
type: object
properties:
type:
type: string
color:
type: string
In the meantime you could just have the query parameter as a plain old string type and then perform the serialization manually, then set the query parameter as required. This is what I'm doing until Swagger UI fully supports OpenAPI 3.0.