Openapi-specification: Optional path parameters

[fabi-o]

Hello,

like described here (https://github.com/wordnik/swagger-ui/issues/380), path parameters are required and can't be optional.

I use optional path parameters in a REST API for filtering, sorting etc.

Example:
www.example.com/users
www.example.com/users:filter=active
www.example.com/users:sort=name
www.example.com/users:filter=active:sort=name

Are there any plans to allow optional parameters in the swagger specifications?

[fehguy]

Hi, in the 2.0 spec, no we are not planning on supporting that. Does that syntax follow a framework or is that your custom design?

[fabi-o]

Ok thank you for that information. It's a custom design, not a framework.

[hekaldama]

@fabi-o, imho I recommend sticking with standards when designing your api. Is there anyway to change to params instead of path for those? If I was consuming your api, the use of :key=value would be confusing and I would much rather use ?key0=value&key1=value.

[fehguy]

closing as not supported in 2.0

[gwicke]

I'm the author of #935 above. In our API we have several paths that end in some optional path segments, and are using /path/with{/optional}{/segment} syntax to avoid duplication of almost-identical path objects. Modeling this as three separate paths would clutter both the spec & the UI with a lot of repetition.

There are quite a few libraries for RFC 6570 URL templates, so the implementation should not be much more work than picking one of those. Related API spec work like JSON schema hypermedia uses RFC 6570 as well. To me it seems that there are few downsides in adopting the full standard in Swagger 2.1.

[gwicke]

@webron, should this task be reopened so that it shows up in https://github.com/swagger-api/swagger-spec/labels/Swagger.Next%20Proposal?

[webron]

It does show up if you look at the opened and closed issues. Anything that's labeled Swagger.Next Proposal will be considered whether it's opened or closed. Once we finish the iteration for the next version, the issues would be relabeled as Swagger.Next Rejected, the version of the new spec or, if deferred, they'll keep the Swagger.Next Proposal label.

I'll reiterate over whether to keep issues as opened or closed and why once I finish my current work on the spec (should be done in a few days), but rest assured that anything that's labeled with Swagger.Next Proposal is open for discussion when we discuss the next version of the spec.

[tjwebb]

Hi, in the 2.0 spec, no we are not planning on supporting that.

There's no possibility for optional route parameters? How would I generate a spec for just about every express.js app which has routes like /foo/:bar?

[webron]

@tjwebb - you won't, at least not with the current version.

[t1]

@fabi-o - if you'd use semicolon instead of colon, you'd be using completely standard matrix parameters ;-)

[webron]

Parent: #574

[bryan5989]

Net core web api supports optional path (route) parameters. I have routes like: /api/chapter/{storyId}/{chapterId?}

where if the chapterId is not specified, the first chapter is returned (or all chapters are returned)
I can't generate a correct spec (using swashbuckle) because {chapterId} parameter is forced to required:true (per the spec, so it's not a swashbuckle problem)

I read somwhere that optional path parameters can't be a thing (due to resource resolution?)- I don't get it. It's a parameter, My implementation can decide if it's required or not, I don't see the need for the specification to dictate it as required always.

Sugar: optional path parameters allow for nicer looking urls (also, other routing schemes work like this.)

[Stalinko]

This feature is really necessary. A lot of frameworks allow optional path-parameters. This is a natural thing, not some hacky trick.
Suggestions to alter the API to work with query-parameters instead of path-parameters sound ridiculous. API mustn't be changed because the documentation tool doesn't support it.

So sadly currently I have to just leave everything as-is and say in description field that this parameter is actually "optional".

[dougbergh]

Any chance this will be addressed? I agree with the prior two commenters, optional path parameters are a natural element of REST APIs, should be supported!

[kurko]

@bryan5989 @Stalinko @dougbergh AFAIK this won't be supported due to this:

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.

I'm not entirely sure on the _non-deterministic_ argument and would love to understand it better, but in general I agree that we should avoid optional path parameters in APIs. I've landed in a few places that used them and it was a mess. I've never seen a case that couldn't be improved with query strings. Also, there are semantic problems with it to the point that new paths are either just new resources (therefore should be documented separately) or filters on the same resource (in which case query strings will do).

If you really want it then maybe you should write a proposal that solves these problems.

[bryan5989]

see my rebuttal: https://github.com/OAI/OpenAPI-Specification/issues/622

@kurko there's not much to propose: make required: false legal in conjunction with in: 'path'