Does Swagger 2.0 support matrix parameters of JAX-RS specification?
JAX-RS specification have Matrix-Parameter support.
I have some matrix parameter present in my application such as /map/color;lat=50;long=20;scale=32000.
I want to derive Swagger for matrix parameters. I use http://editor.swagger.io; but I could not got any help in the editor. Can anyone help me?
Does Swagger 2.0 support matrix parameters?
Other links ralted to matrix param:
https://www.w3.org/DesignIssues/MatrixURIs.html
https://www.safaribooksonline.com/library/view/restful-java-with/9780596809300/ch05s03.html
OpenAPI/Swagger 2.0 does not support matrix parameters, but they are supported in OpenAPI 3.0.
Using OpenAPI 3.0, your example:
/map/color;lat=50;long=20;scale=32000
can be defined as:
openapi: 3.0.1
...
paths:
/map/color{params}:
get:
parameters:
- in: path
name: params
required: true
# Named matrix parameters are defined as object properties
schema:
type: object
properties:
lat:
type: integer
example: 50
long:
type: integer
example: 20
scale:
type: integer
example: 32000
# Serialize this object as ;prop1=value2;prop2=value2 etc
style: matrix
explode: true
Swagger UI/Editor Support
This is supported in Swagger UI 3.15.0+ and Swagger Editor 3.5.6+. In the parameter editor, enter the parameter names and values in the JSON object format, e.g.:
{
"lat": 50,
"long": 20,
"scale": 32000
}
"Try it out" will send these parameters as matrix parameters in the URL:
Swagger-Core Support
For those using Java annotations, #MatrixParam is supported in swagger-core 2.0. #MatrixParam corresponds to OpenAPI 3.0's path parameters with style: matrix (as in the example above).
Swagger 2.0 spec does not mention anything about JAX-RS Matrix parameter.
Also looking at the swagger-jaxrs implementation, you can see that #MatrixParam is ignored in the class responsible for scanning JAX-RS parameter annotations.
Related
I am creating a well-organized OAS3 swagger documentation on swaggerhub. For every endpoint i am writing all possible answers like 200, 201, 204, 400, 401, 403, 404, 500 etc. In addition all methods have default parameters like X-Language-Code etc.
I am in such a place that the responses, models, parameters I use now begin to repeat themselves in each file. After a little research i learnt that i can create a domain and remote absolute url references to them.
There is no error when i used the 'definition's remotely like this:
/example:
get:
#some other informations here
responses:
200:
description: 'example description'
content:
application/json:
schema:
$ref: 'https://remote.example/url/2.0#/definitions/ExampleResponse'
But, apparently you can not use $ref keyword right below responses or 400 etc.. keyword like this:
This one not getting error but not rendering the remote reference
responses:
400:
$ref: 'https://remote.example/url/2.0#/responses/Error400'
or this:
This one gives error
responses:
$ref: 'https://remote.example/url/2.0#/responses'
Even, i can not use 'parameters' as i expected:
/example:
get:
parameters:
- languageCode:
$ref: 'https://remote.example/url/2.0#/parameters/languageCode'
/example:
get:
parameters:
- $ref: 'https://remote.example/url/2.0#/parameters/'
I dont want to rewrite all reference definitions below every documentation.
I am confused about using and referencing 'domain's. Can someone explain or referencing a document about this situations since i couldn't found any documentation about it.
Update: OpenAPI 3.0 domains are now supported in SwaggerHub.
As of December 2018, SwaggerHub domains only support the OpenAPI 2.0 syntax but not OpenAPI 3.0. OpenAPI 3.0 and 2.0 use slightly different syntax for parameters, responses, etc., this means you cannot reference an OAS2 domain from an OAS3 API definition.
The workaround is to create another OpenAPI 3.0 API in SwaggerHub and use it as a "domain". You'll need to add a dummy header with openapi: 3.0.0, the info section and empty paths: {} to make the validator happy.
openapi: 3.0.0
info:
title: Common components
version: 1.0.0
paths: {}
# Put your common components here:
components:
schemas:
...
parameters:
...
responses:
...
Then you can reference components from this "domain" using the usual $ref syntax:
$ref: 'https://api.swaggerhub.com/apis/USERNAME/API-NAME/VERSION#/components/responses/Error400'
Make sure the hostname in $refs is API.swaggerhub.com (not APP.swaggerhub.com) and the link contains /apis/ (not /domains/).
I have an endpoint with query parameters that use square brackets:
GET /info?sort[name]=1&sort[age]=-1
Here, name and age are the field names from my model definition.
How can I write an OpenAPI (Swagger) definition for these parameters?
It depends on which version of OpenAPI (Swagger) you use.
OpenAPI 3.x
The sort parameter can be defined an an object with the name and age properties. The parameter serialization method should be style: deepObject and explode: true.
openapi: 3.0.0
...
paths:
/info:
get:
parameters:
- in: query
name: sort
schema:
type: object
properties:
name:
type: integer
example: 1
age:
type: integer
example: -1
style: deepObject
explode: true
responses:
'200':
description: OK
This is supported in Swagger UI 3.15.0+ and Swagger-Editor 3.5.6+.
Important: The deepObject serialization style only supports simple non-nested objects with primitive properties, such as in the example above. The behavior for nested objects and arrays of objects is not defined.
In other words, while we can define
?param[foo]=...¶m[bar]=...
there's currently no way to define more nested query parameters such as
?param[0][foo]=...¶m[1][bar]=...
or
?param[foo][0][smth]=...&?param[foo][1][smth]=
If you need the syntax for deeply nested query parameters, upvote and follow this feature request:
Support deep objects for query parameters with deepObject style
OpenAPI 2.0 (Swagger 2.0)
sort[name] and sort[age] need to be defined as individual parameters:
swagger: '2.0'
...
paths:
/info:
get:
parameters:
- in: query
name: sort[name]
type: integer
- in: query
name: sort[age]
type: integer
responses:
200:
description: OK
How to specify a property as null or a reference? discusses how to specify a property as null or a reference using jsonschema.
I'm looking to do the same thing with swagger.
To recap the answer to the above, with jsonschema, one could do this:
{
"definitions": {
"Foo": {
# some complex object
}
},
"type": "object",
"properties": {
"foo": {
"oneOf": [
{"$ref": "#/definitions/Foo"},
{"type": "null"}
]
}
}
}
The key point to the answer was the use of oneOf.
The key points to my question:
I have a complex object which I want to keep DRY so I put it in a
definitions section for reuse throughout my swagger spec: values of other properties; response objects, etc.
In various places in my spec a
property may be a reference to such an object OR be null.
How do I specify this with Swagger which doesn't support oneOf or
anyOf?
Note: some swagger implementations use x-nullable (or some-such) to specify a property value can be null, however, $ref replaces the object with what it references, so it would appear any use of x-nullable is ignored.
OpenAPI 3.1
Define the property as anyOf of the $ref and type: 'null'.
YAML version:
foo:
anyOf:
- type: 'null' # Note the quotes around 'null'
- $ref: '#/components/schemas/Foo'
JSON version:
"foo": {
"anyOf": [
{ "type": "null" },
{ "$ref": "#/components/schemas/Foo" }
]
}
Why use anyOf and not oneOf? oneOf will fail validation if the referenced schema itself allows nulls, whereas anyOf will work.
OpenAPI 3.0
YAML version:
foo:
nullable: true
allOf:
- $ref: '#/components/schemas/Foo'
JSON version:
"foo": {
"nullable": true,
"allOf": [
{ "$ref": "#/components/schemas/Foo" }
]
}
In OAS 3.0, wrapping $ref into allOf is needed to combine the $ref with other keywords - because $ref overwrites any sibling keywords. This is further discussed in the OpenAPI Specification repository: Reference objects don't combine well with “nullable”
Not easy to do that. Even almost impossible. Your options :
Wait
There is a very long discussion about this point, maybe one day it will be done...
Use vendors extensions
You can use vendors extensions like x-oneOf and x-anyOf. I have already taken this hard way: You must to upgrade all used 'swagger tools' to take into account these vendors extensions.
In my case, we needed 'only' to :
Develops our own Jax-RS parser with customized annotations in order to extract swagger API file from sources
Extends swagger-codegen to take into account these extensions to generate java code for our clients
Develops our own swagger-ui: to facilitate this work, we added a preprocessing step to convert our swagger schema with our extensions to a valid json schema. It's easier to find a module to represent json schemas than swagger schemas in javascript. By cons we gave up the idea to test the API with the 'try it' button.
It was a year ago, maybe now ...
Refactor your APIs
Many projects don't need anyOf and oneOf, why not us ?
For OpenAPI 3.0 for some reason using nullable: true followed by allOf didn't work for the OpenAPI interpreter I'm using. As a workaround I ended up defining a must-be-null ref called null_type that I can use in an anyOf construct.
Like so:
allOf:
- anyOf:
- $ref: "#/components/schemas/null_type"
- $ref: "#/components/schemas/your_ref"
- description: "optionally add other properties here..."
where:
schemas:
null_type:
title: "OpenAPI 3.0 null-type ref"
description: "for adding nullability to a ref"
enum: [null]
your_ref:
...
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.
I am trying to use Swagger to define an API that accepts an actual file and a schema object that describes the contents of a file. Here is a snippet of the Swagger YAML. However it won't validate in the Swagger Editor.
/document:
post:
summary: Api Summary
description: Api Description
consumes:
- multipart/form-data
parameters:
- name: documentDetails
in: formData
description: Document Details
required: true
schema:
$ref: '#/definitions/Document'
- name: document
in: formData
description: The actual document
required: true
type: file
The Swagger Editor throws the following validation error:
Swagger Error: Data does not match any schemas from 'oneOf'
Am I missing something? Or Is this not a supported feature of Swagger?
This is possible in OpenAPI 3.0, but not in OpenAPI/Swagger 2.0.
OpenAPI/Swagger 2.0 does not support objects in form data. Form parameters can be primitive values, arrays of primitives, and files, but not objects. So your example cannot be described using OpenAPI 2.0.
In OpenAPI 3.0, you can use:
paths:
/document:
post:
summary: Api Summary
description: Api Description
requestBody:
required: true
content:
multipart/form-data:
# Form parameters from 2.0 become body schema properties in 3.0
schema:
type: object
properties:
# Schema properties correspond to individual parts
# of the multipart request
document:
# In 3.0, files are binary strings
type: string
format: binary
description: The actual document
documentDetails:
$ref: '#/components/schemas/Document'
# The default Content-Type for objects is `application/json`
required:
- document
- documentDetails
Relevant parts of the 3.0 Specification:
Considerations for File Uploads
Special Considerations for multipart Content
swagger does not support type 'object' in formData, only as body parameters.
It is not possible using Swagger 2.0 , you can only read it as a type 'file' ,
https://swagger.io/docs/specification/2-0/file-upload/
On a related note please be aware that uploading array of files is also not supported in Swagger 2.0 but it is supported in Open API 3.0 .
https://github.com/OAI/OpenAPI-Specification/issues/254