69

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.

Helen
  • 87,344
  • 17
  • 243
  • 314
Hedeshy
  • 1,266
  • 2
  • 15
  • 24

6 Answers6

69

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
Tgr
  • 27,442
  • 12
  • 81
  • 118
William Cheng
  • 10,137
  • 5
  • 54
  • 79
  • I came here searching for a solution of a bit different problem. I get these errors very often when converting from WADL to Swagger using The API Transformer. For now I'm resolving these manually by adding two separate routes. I'm in search for a better converter that adds all the endpoints automatically instead of marking required as false and failing. – vezenkov Oct 05 '16 at 14:08
  • @vezenkov have you tried https://github.com/lucybot/api-spec-converter to do the conversion? – William Cheng Oct 05 '16 at 16:26
  • 2
    Sorry but you don't answer to the question at all. Please give a clear answer `It's not possible` if it's really not possible and give an alternative if you want. – amdev Jun 13 '19 at 11:33
29

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.

Jerrod Horton
  • 1,605
  • 1
  • 15
  • 30
  • 2
    Unfortunately I don't think you will be able to have an optional parameter in the "path". It is not a Swagger thing, but rather how the URL schema works. If you have GET /products/{id} and you say that {id} is optional then you have completely changed the url that the resource is targeting (i.e. now GET /products). Perhaps you could take this back to them and ask them why they want an optional parameter in the base uri. I work with REST APIs a lot and this sounds like a case where the request/resource may need to be thought out a bit more to solve the problem. Good luck! – Jerrod Horton Jan 27 '16 at 14:36
  • Does query work if i have following endpoints: /resource?querystring and /resource/{id} ? Can {id} be distinguished from query parameters? – Gobliins Jun 29 '16 at 10:29
  • 2
    Well, last part of url can be optional without blowing up anything, without this parameter you get the list, with this parameter you get a given item. This is a problem in Swagger, not in the Web API Swagger is trying to document. – Frode Nilsen Jan 24 '18 at 12:52
  • This does not works. Validation of the JSON fails. – Peter Stegnar Oct 25 '21 at 09:12
5

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)

Paulo Oliveira
  • 2,411
  • 1
  • 31
  • 47
5

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.

Stalinko
  • 3,319
  • 28
  • 31
1

Try adding 2 endpoints for the same API. like

/get/{param1}/{param2} and /get/{param1}/{param2}/{param3}

Satya Pendem
  • 307
  • 5
  • 13
0

In laravel or nelmio bundle for symfony works:

@OA\Parameter(
name="param2",
description="Param 2",
in="path",
allowEmptyValue=true,
example="1234",
required=false,

Im not sure if in works in yaml for swagger. But should work.

Den
  • 19
  • 1
  • 6
  • Thank you for your interest in contributing to the Stack Overflow community. This question already has quite a few answers—including one that has been extensively validated by the community. Are you certain your approach hasn’t been given previously? **If so, it would be useful to explain how your approach is different, under what circumstances your approach might be preferred, and/or why you think the previous answers aren’t sufficient.** Can you kindly [edit] your answer to offer an explanation? – Jeremy Caney Aug 24 '23 at 01:03