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)

[DavidBiesack]

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.

[bkeeler-redox]

Wow, this is a big gap in OpenAPI, so it’s quite surprising to see how long this discussion has been ongoing.