OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Support an operation to have multiple specifications per path (e.g. multiple POST operation per path)
with POST actions especially, there can be several unrelated operations that would be better presented to the user as separate POST actions in swagger-ui because they do very different things to the same resource. Each of these different operations should have a unique description string and unique media types to select from and other unique parameters (such as query parameters), and thus have separate presentation in swagger-ui. By simply allowing only just schema overloading, there is no way for me to constrain query parameter A to be used with just media type X, and query parameter B to be used with media type Y. These are implemented as two independent operations and it would be nice to be able to model them independently in Swagger.
So I think a proposal i saw elsewhere to annotate the operations themselves (to provide unique keys in the JSON object) would actually be more flexible than other workarounds to the fact that Swagger only allows one POST per path when a REST API may in fact support many independent POST calls.
i.e. something like
paths:
/a/b/c:
get: ....
put: ...
post.optimize: spec for the optimize operation
post.merge: spec for the merge operation
(Initially discussed in #146)
Real world example - OpenStack Server Actions. I've been trying to convert OpenStack WADL to Swagger and these operations have been a sticking point. There's no real way to describe them right now, because the Swagger doesn't allow path (which is what the WADL uses), nor does it allow "oneOf" or "anyOf" schemas. So I don't see any possible way to describe these services right now.
On the other hand, I want Swagger to define an API, not just describe it. That's the whole reason the working group decided to avoid some of these features in the first place - to avoid ambiguity. If this is going to be done it needs to be done in a way that works for:
- Code generators (like swagger-codegen)
- Stub servers
- Testing tools
It's basically a routing problem: given an HTTP request you should know what operation is being called, and this makes it ambiguous.
+100!
Recently we had to change our api because were unable to define multiple post methods per path. So api became uglier in favour of its documentation.
This is a feature of Swagger's opinion on APIs. For better or worse, it presumes that the signature of an operation is the resource path pattern plus the HTTP verb.
To change this would require an alternate mechanism for defining the signature. If we do pick this up in Swagger.next, then let's consider an overloading of a method with some sort of signature property. I'm not sure that this is something that it SHOULD do, but that is how I would tackle it. (and I agree with what @maxlinc said above)
I recently came across the same problem and would love to have the ability to define the API and associate the same path with multiple endpoints that are still unique.
So I'd like to suggest that endpoints are not defined by their paths, but by a user defined key name. More than likely it'll be a domain specific operation name (eg: 'addBookByJson','addBookByBinary' may both have the same path but different endpoints/consumes). Then each endpoint would have a path associated with it instead of 'being' the path directly. Ambiguity is still easy to check based on an equality function of all defined endpoints (which could then be based on implementing platform which might be more applicable rather than defining the equality relation in the swagger API).
There are so many ways I could define an endpoint based on an HTTP request. And if swagger is to be a general tool for documentation, then I would much rather see swagger show its opinions in the form of defaults (or the easy path), NOT by limiting functionality when I need to go outside of the norm to support others or implement new ideas!
+1 This would make the tool much more fliexible. I totally agree with @earth2marsh on this point. Allow the user decide what properties of an http request determine its signature.
+1
This would be really fantastic:
{
"in": "body",
"name": "abstractThing",
"schema": {
"oneOf": [
{
"$ref": "#/definitions/ConcreteThing"
},
{
"$ref": "#/definitions/ConcreteOtherThing"
}
]
}
}
+1
Recently we had to change our api because were unable to define multiple post methods per path. So api became uglier in favour of its documentation.
Feels a bit like the tail wagging the dog.
What we are doing in the interim is to use #tag in the paths to differentiate these.
/a/b/c: post: /a/b/c#merge: post:
We have customized Swagger UI to hide these tags and remove them from the Try It/curl actions
Each of these post operations can have their own parameters/produces/consumes.
I realize that almost none of the existing Swagger ecosystem will work with this, but we need to move forward, and this is the path we're taking. It was the easiest and lowest impact change to Swagger UI and the swagger documents, and it works fairly well. Our expectation is to be able to transform our use to wherever Swagger.Next goes.
Another possible format for modelling this, not perfect though either. It comes out of the REST principle that you use the verb. Now REST over HTTP forces verb to be GET,POST,etc and they suggest you use an _method parameter or some override parameter to POST operations to indicate your real verb. So with that in mind we could define a paramter with a special type or mark it someway as your verb-override parameter for the specific end point and then change the verb to what you want.
Would look something like this:
paths:
/some/path
parameters:
_method:
type: string
verb-override: true
post:
....
copy:
....
merge:
....
With this, anything that falls outside of the standard HTTP verbs are modelled as POST /some/path?_method=copy. It could also then be used for those servers that only support PATCH or other standard HTTP but not as well supported verbs through a method override.
I am really hoping that this proposal will be accepted, to index APIs by their logical name instead of path.
I have a set of existing APIs that offer various content-type/accept combinations to accommodate various clients and use cases, and it's not possible to describe them in one openapi 2.0 document.
My temporary solution is to just have a separate openapi document for each use case, so that the inputs and outputs are appropriately bound together. I had to factor out all of the common definitions to external files in order to minimize the boilerplate.
This particular proposal is not for 3.0, however with https://github.com/OAI/OpenAPI-Specification/pull/798 you can now specify different input and output schemas based on content type. Please read through that and hopefully that will satisfy your use case.
From my initial reading of this, #146, and #791 this appears to cover what many folks were asking for (might even be usable for some of the protobuf-encoding extensions suggested in #801 ??)
I'm not up to speed on the "opinionated" aspects of the OpenAPI model but the idea of generic overloading based on parameters makes me a bit uneasy. Having more strongly defined variants for consuming clients is certainly a good thing to strive for but I'm a bit leary of allowing idiosyncrasies of various controller binding models leaking through into a standard (essentially the UI vs implementation argument put forward by @DavidBiesack in #146 )
@caitsithx see my comment https://github.com/OAI/OpenAPI-Specification/issues/182#issuecomment-250600331 for what is happening with 3.0
