OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Optional path parameters
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?
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, 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.
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.
@webron, should this task be reopened so that it shows up in https://github.com/swagger-api/swagger-spec/labels/Swagger.Next%20Proposal?
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.
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?
@fabi-o - if you'd use semicolon instead of colon, you'd be using completely standard matrix parameters ;-)
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.)
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".
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!
@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 withPOST: /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.
see my rebuttal: https://github.com/OAI/OpenAPI-Specification/issues/622#issuecomment-701045346
@kurko there's not much to propose: make required: false legal in conjunction with in: 'path'
Was this issue even acknowledged during recent updates, or do devs just refuse to add optional path parameter support? I'm experimenting with generating API input validation based on openapi3 spec, which is currently impossible for optional parameter endpoints.
2 years later, I've realized that I misused the term resource in my final thought above (https://github.com/OAI/OpenAPI-Specification/issues/622#issuecomment-1067381861). That said, I restate my point that an OAS pathspec does not determine whether you'll get a resource or something else (not a resource) at that path. That's for I the implementer to decide. Which is the whole point of documenting an API in the first place and the reason why OAS should allow me to decide whether a path segment is optional or not. Generator implementors can add switches to honor/ignore that preference.
i just end up creating a new path for each. couldnt find a workaround
not sure if this would be solved tho with the above proposal.
i got here cause i hate making 2 parameters (headers) for each item i want.. 1 is required the other not (when using $ref) which is totaly off topic to this thread i know. but im still looking...
For OAS 4.0 (Moonwalk), we plan to use proper URI Templates, which allow path variable expansion. I believe that will address this use case. If not, please open a discussion in the Moonwalk repository.
I don't think this could be done in 3.x even if we wanted to, due to compatibility and tooling support issues. Therefore I'll close this in favor of the existing Moonwalk proposal.
