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}
Related
I have created a RESTful API, and I am now defining the Open API 3.0 JSON representation for the usage of this API.
I am requiring usage of a parameter conditionally, when another parameter is present. So I can't really use either required: true or required: false because it needs to be conditional. Should I just define it as required: false, and then in the summary and / or description say that it is required when the other parameter is being used? Or is there a way of defining dependency between parameters? I haven't found anything in the specs that mention a case like this.
From the docs:
Parameter Dependencies
OpenAPI 3.0 does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at github.com/OAI/OpenAPI-Specification/issues/256. What you can do is document the restrictions in the parameter description and define the logic in the 400 Bad Request response.
For more info - swagger.io/docs/specification/describing-parameters
See https://community.smartbear.com/t5/Swagger-Open-Source-Tools/Defining-conditional-attributes-in-OpenAPI/td-p/222410 where you can use anyOf around the required list of field
anyOf:
- required: [longitude, latitude]
- required: [postalCode, countryCode]
- required: [city, state, countryCode]
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.
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.)