Openapi-specification: Support optional path parameters with default value

[amarzavery]

As of today, Open API spec asserts that a path parameter should always be required. This is a good assertion.
However, we have some services in Azure that have optional path parameters with a default value. There has been an increasing number of requests from service teams to support this.

What do you think about the following assertion?

If the parameter is in "path", required field must be specified. If required is false, it must be supported with a default. Else, required filed should be true.

This provides more flexibility apart from taking care of the current assertion.

For example:

• "/kevault/{KeyType}"

{
  "name": "KeyType", 
  "in": "path", 
  "required": false,
  "default": "symmetric",
  "type": "string", 
  "description": "The type of key."           
}

Can this be included in the 3.0 version of the Open API Spec?

[webron]

Given the planned support for some other aspects of RFC6570, the requirement that path parameters are mandatory may drop altogether.

[amarzavery]

That would really awesome :)

[amarzavery]

Do you have a time range for when will the next version be public?

[webron]

Within a few months. The process itself is public so people can voice their opinions as we progress.

[fehguy]

Parent issue #574

[darrelmiller]

@amarzavery As noted on the original Autorest issue, 6570 optional path parameters wouldn't quite meet the needs of the original example.

[swettstein]

Given the planned support for some other aspects of RFC6570, the requirement that path parameters are mandatory may drop altogether.

and yet 3 1/2 years later, they still appear to be mandatory

[fehguy]

I think @webron used the word "may" because it's not for sure changing...

[swettstein]

i have seen lots of discussions about path parameters containing slashes but nothing on this issue regarding simple path parameters.

from what i've read so far, OAS is designed to be how one SHOULD describe an API, not meant to support how APIs have actually been implemented. if that is indeed accurate, then why SHOULD path parameters be mandatory?

[fehguy]

Quite simply, making path parameters optional _changes the path semantics_ and can make resolution of the operation non-deterministic. I know we can all think of one-off use cases where one can justify why it makes sense that POST: /foo/{bar}/{baz}/{bat} may not overlap with POST: /foo/123 (bat was optional) but in the general case, it makes routing difficult to impossible.

[bryan5989]

@fehguy I disagree with your non-determinism comment. I argue that path resolution is non-deterministic by default. For example:

blog.domain/api/post/latest

Is deterministic because it always processes the same logic to reliably retrieve the latest blog post. It's also non-deterministic because there's no guarantee that between calls the same blog post will be retrieved.

blog.domain/api/post/1
blog.domain/api/post/2
blog.domain/api/post/3

Are deterministic because they always return the exact same post respectively. However, you're nuts if you think I'm going to specify a path for every post that exists (extreme example) <- and revise my spec every time a new blog post is created.

OAS is a specification for _describing_ an API. It is not an example or reference for _how_ an API should be implemented nor does it have anything to do with how path resolution is implemented.

_I_ implement my API and _I_ wish to document it. I wish to document it in a standard way to that doc generation tools can _deterministically_ (reliably) generate the docs _accurately_. _I_ have optional path (route) parameters. I cannot trust that _any_ doc generator will correctly generate a doc for my API because if the generator is OAS-compliant, it MAY ignore or throw an error when it encounters required: false in a parameter definition that also includes in: 'path'.

This is an unreasonable restriction.

EDIT: (forgot to finish my thought)
In all cases, blog.domain/api/post/ irrespective of what follows reaches the same resource on my server which then decides how to handle what comes after the '/' <- but that's _my_ implementation choice, and I currently have no way of documenting that. I may, for example, wish that for the case of no argument, return the latest by default or a collection of posts.

[KenEucker]

Jumping in here late to say that I also wish for this to be implemented. My use case is the same as @bryan5989 above, in that I have paths:

blog.domain/api/post/1
blog.domain/api/post/2
blog.domain/api/post/3

and I also have

blog.domain/api/post/latest

My server receives requests at the root blog.domain/api/post/ synonymous with the requests above by provided POST values. My path looks like this:

     * /api/post/{post_id}:
     *   post:
     *     parameters:
     *       - in: formData
     *         name: post_id
     *       - in: path
     *         name: post_id

So a POST request to blog.domain/api/post/ with the body { post_id: "latest" } receives the same response as blog.domain/api/post/latest provides. And requests that come in at /api/post/ without the {post_id} parameter receive the same response as /api/post/latest (default: "latest").

This is how my application is structured and I would like for it to be documented properly. The reason I would like to be able to document this properly is so that my generated API requests are properly formatted. Right now, when using swagger-ui to connect using my given swagger.json, requests without filling in the optional path parameter look like this:

POST blog.domain/api/post/undefined