I'm working on an API spec in swagger that has an endpoint:
/authorizations
I would like to define an alternative spelling (authorisations) for this endpoint as well. Is this possible? Or do I need to define a separate route for each spelling?
/authorizations:
get:
description: Returns a list of authorizations
A possible workaround is to define another path that $refs the original path, this way you end up with two copies of the same path.
paths:
/authorizations:
get:
description: Returns a list of authorizations
responses:
200:
description: OK
/authorisations:
$ref: '#/paths/~1authorizations'
One limitation of this technique is that you cannot have operationId for these paths, because both paths will end up with the same ID, which is not allowed.
If you need to have different operationId in paths, you'll need to define the 2nd path in the usual way (i.e. copy-paste the definition from the 1st path).
Swagger currently does not support overloading/aliasing path definitions. I don't recall ever seeing such a request, but you're more than welcome on open an issue on https://github.com/wordnik/swagger-spec asking to add support for it in future versions.
See https://github.com/OAI/OpenAPI-Specification/issues/213 where one suggestion is to define a "renamed" path by using a 308 redirect:
/original-x:
description: Redirects to the new X
get:
responses:
'308':
description: This resource has been moved
headers:
Location:
schema:
type: string
default: /new-x
(I've not seen another means to implement this cleanly.)
Related
Can you use both a path parameter and a query parameter in Swagger 2.0 or 3.0? For example, given the following base URL and path parameter:
/api.example.com/{path}
is it possible to add a query parameter, as in:
/api.example.com/{path}?<query_param>=<query_value>
My use case is the DELETE operation: {path} refers to an object ID to be deleted, and I'd like to add a flag so the requester can specify whether to try and force delete an object that ordinarily would not be deletable (think deleting a non-empty directory in Linux with rm -f). The URLs would then look like:
/api.example.com/{objectID123} (regular delete; will fail if object is non-empty)
/api.example.com/{objectID123}?forceDelete=True (force delete)
I know I can specify both the object ID and the forceDelete flag as query parameters, but that would mean rewriting the DELETE operation as based solely on query parameters, while the other operations are all based on path parameters; I was hoping to keep everything consistent.
I read the documentation, but didn't find this question addressed explicitly. Note that I'm open to another way to handle the DELETE operation if there are best practices I'm not aware of.
Yes, you can have different parameter types in the same operation.
openapi: 3.0.2
...
paths:
/api.example.com/{objectID}:
delete:
parameters:
- in: path
name: objectID
required: true
schema:
type: integer
- in: query
name: forceDelete
schema:
type: boolean
default: false
I'm trying to turn the Atom Publishing Protocol (RFC5023) in to a Swagger / OpenAPI spec to exercise writing those specs.
I ran into the following problem: in Atom there are different types of URIs, e.g. Collection and Member URIs.
My idea was to document it like this:
paths:
/{CollectionURI}:
get:
summary: List Collection Members
...
post:
summary: Create a Resource
...
parameters:
- $ref: "#/parameters/CollectionURI"
/{MemberURI}:
get:
summary: Retrieve a Resource
...
parameters:
- $ref: "#/parameters/MemberURI"
When I do that, swagger-editor claims that
Equivalent path already exists: /{MemberURI}
Those are different types of URIs that return different things when queried. I want to call them differently to document them individually.
Is there any way to do this?
Thanks!
EDIT:
The spec shows up just fine in Swagger-UI -- is this a bug in the editor or does the UI just ignore my error?
That's because the two paths can be identical. I understand that the parameters may uniquely identify them, but OpenAPI 2.0 (Swagger 2.0), 3.0 and 3.1 do not support full URI templates, and the path portion alone is inspected for uniqueness. So these:
/{foo}
/{bar}
are identical, even if foo must be a string, and bar must be a number. Please add your $0.02 on the OpenAPI Specification Repo as we're working on better path support right now.
I'm trying to turn the Atom Publishing Protocol (RFC5023) in to a Swagger / OpenAPI spec to exercise writing those specs.
I ran into the following problem: in Atom there are different types of URIs, e.g. Collection and Member URIs.
My idea was to document it like this:
paths:
/{CollectionURI}:
get:
summary: List Collection Members
...
post:
summary: Create a Resource
...
parameters:
- $ref: "#/parameters/CollectionURI"
/{MemberURI}:
get:
summary: Retrieve a Resource
...
parameters:
- $ref: "#/parameters/MemberURI"
When I do that, swagger-editor claims that
Equivalent path already exists: /{MemberURI}
Those are different types of URIs that return different things when queried. I want to call them differently to document them individually.
Is there any way to do this?
Thanks!
EDIT:
The spec shows up just fine in Swagger-UI -- is this a bug in the editor or does the UI just ignore my error?
That's because the two paths can be identical. I understand that the parameters may uniquely identify them, but OpenAPI 2.0 (Swagger 2.0), 3.0 and 3.1 do not support full URI templates, and the path portion alone is inspected for uniqueness. So these:
/{foo}
/{bar}
are identical, even if foo must be a string, and bar must be a number. Please add your $0.02 on the OpenAPI Specification Repo as we're working on better path support right now.
This question is not a duplicate of (Swagger - Specify Optional Object Property or Multiple Responses) because that OP was trying to return a 200 or a 400.
I have a GET with an optional parameter; e.g., GET /endpoint?selector=foo.
I want to return a 200 whose schema is different based on whether the parameter was passed, e.g.,:
GET /endpoint -> {200, schema_1}
GET /endpoint?selector=blah -> {200, schema_2}
In the yaml, I tried having two 200 codes, but the viewer squashes them down as if I only specified one.
Is there a way to do this?
Edit: the following seems related: https://github.com/OAI/OpenAPI-Specification/issues/270
OpenAPI 2.0
OAS2 does not support multiple response schemas per status code. You can only have a single schema, for example, a free-form object (type: object without properties).
OpenAPI 3.x
In OAS3 you can use oneOf to define multiple possible request bodies or response bodies for the same operation:
openapi: 3.0.0
...
paths:
/path:
get:
responses:
'200':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResponseOne'
- $ref: '#/components/schemas/ResponseTwo'
However, it's not possible to map specific response schemas to specific parameter values. You'll need to document these specifics verbally in the description of the response, operation and/or parameter.
Here's a possibly related enhancement request:
Allow operationObject overloading with get-^ post-^ etc
Note for Swagger UI users: Older versions of Swagger UI (before v. 3.39.0) do not automatically generate examples for oneOf and anyOf schemas. As a workaround, you can specify a response example or examples manually. Note that using multiple examples require Swagger UI 3.23.0+ or Swagger Editor 3.6.31+.
responses:
'200':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResponseOne'
- $ref: '#/components/schemas/ResponseTwo'
example: # <--- Workaround for Swagger UI < 3.39.0
foo: bar
I wanted the same thing, and I came up with a workaround that seems to work:
I´ve just defined two different paths:
/path:
(...)
responses:
200:
description: Sucesso
schema:
$ref: '#/definitions/ResponseOne'
(...)
/path?parameter=value:
(...)
responses:
200:
description: Sucesso
schema:
$ref: '#/definitions/ResponseTwo'
(...)
Paths do work on swagger editor. I can even document each option differently and put optional parameters that only may be on the second case toguether, making the API doc much cleaner. Using operationId you may generate cleaner names for the generated API methods.
I´ve posted the same solution here (https://github.com/OAI/OpenAPI-Specification/issues/270) to verify if I am missing something more.
I do understand it is not explicitly allowed/encouraged to do it (neither I found some place explicitly disallowing it). But as a workaround, and being the only way to document an API with this behaviour in the current specification,, looks like an option.
Two problems I´ve found out with it:
Java code gen URL escapes the "=" sign, therefore it wont work unless
you fix this in the generated code. Probably it happens in other code
generators.
If you have more query params it will add an extra "?" and fail;
If those are not blockers, it at least will allow you to document properly such cases and allow testing with swagger editor.
There is a function in my REST web service working with GET method and it has two optional parameters.
I tried to define it in Swagger but I encountered an error, Not a valid parameter definition, after I set the required as false.
I found out that if I set the required value as true the error will be gone. Here is a sample of my Swagger code.
...
paths:
'/get/{param1}/{param2}':
get:
...
parameters:
- name: param1
in: path
description: 'description regarding param1'
required: false
type: string
- name: param2
in: path
description: 'description regarding param2'
required: false
type: string
I didn't experience this with parameters in body or the the ones in query. I think this problem is only related to parameters in path. I could not find any solution in swagger specification files either.
Is there any other way to define optional parameters in Swagger or do I have any mistake in my code?
Any help would be appreciated.
Given that path parameter must be required according to the OpenAPI/Swagger spec, you can consider adding 2 separate endpoints with the following paths:
/get/{param1}/{param2} when param2 is provided
/get/{param1}/ when param2 is not provided
It it likely blowing up because you cannot have a base uri parameter optional, only query string values (in the case of a url).
For example:
GET /products/{id}/pricing?foo=bar
** If foo is optional then your IN parameter needs to be "query" not "path"
** If {id} is optional then something is wrong. {id} can't be optional because it is contained within the base uri.
This should work:
{
"in":"query",
"required":false
}
This should not work
{
"in":"path",
"required":false
}
change your "in" property to be "query" instead of "path" and it should work.
Your YAML fails because as it stated on the specification:
Determines whether this parameter is mandatory. If the parameter is in "path", this property is required and its value MUST be true.
Source: http://swagger.io/specification/#parameterObject (Look in fixed fields table)
Sad but fact there is no official support for optional parameters still in 2020 and in 3.* specification:
https://github.com/OAI/OpenAPI-Specification/issues/93
You can only apply some workaround mentioned in other answers (describe several endpoints for every set of parameters; convert your API to work with query-parameters instead of path-parameters).
Personally I decided to just leave everything as is, just add a parameter description which clearly says "This parameter is OPTIONAL!". Should be clear enough for everyone who reads the API.
Try adding 2 endpoints for the same API. like
/get/{param1}/{param2} and /get/{param1}/{param2}/{param3}