Support optional path parameters with default value

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?

[SheepReaper]

@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