Allow operationObject overloading with get-^ post-^ etc

Currently under a pathItemObject, one can only define a single operationObject for each HTTP method (get, put, post, delete) etc. .

This limits OAS’ ability to express many APIs, particularly those which allow multiple semantically different POST or GET operations on the same resource, such as different sets of query parameters or produces/consumes media types and associated schema.

This is a request to explicitly allow for this. Several other OAI/OpenAPI-Specification issues touch on this (notably #146 and the many issues which referred to it since 2014), but an explicit proposal to resolve this and allow overloading so is not yet forthcoming (or if it is, I’m not sure where it is…)

The proposal is to allow pathItemObject with new patterned fields corresponding to each operation. That is in addition to

  get
  put
  post
  patch
  delete
  head
  options

we also allow patterned names

  get-^
  put-^
  post-^
  patch-^
  delete-^
  head-^
  options-^

This differs from my initial proposal in #146 which used period (.) as a separator instead of hyphen (-), i.e. post.optimize, post.merge.

@darrelmiller also noted he was considering this, using the hyphen (-) notation:

paths:
   /customers:
       get-by-email:
          parameters:
              email: ...
          responses: ...
       get-by-name:
          parameters:
              firstname: ...
              lastname: ...
          responses: ...

I feel segregation into individual operationObjects is the best solution because it is a natural extension of the current syntax (compared to turning a path item into an array) or complicating a operationObject with multiple sets of body/header/query parameters and/or response schema (which might require adding complicated discriminators/tags or other ways to link related response/parameters within one large all-encompasing operation object.)

[darrelmiller]

@MikeRalphson The hope was to make these scenarios something you didn’t have to “workaround”. I don’t like idea of telling people to put things in the path key that are not part of the URL path.

[darrelmiller]

It’s not uglier than putting fragments on the end of paths. Or using oneOf in the schema and creating a union of query parameters. And it is definitely not uglier than the x-ms-paths solution.

I have no problem if OpenAPI wants to enforce that “style” of HTTP API, but we need to recognize that we are preventing people with perfectly valid HTTP APIs from being able to use OpenAPI to describe their APIs.