Using operation Id to overload HTTP methods or passing an array of operations to HTTP methods

[VamshikShetty]

Current openapi 3.0.0 basic structure :

{
  	"openapi": "3.0.0",
  	"servers": [ ],
  	"info": { },
  	"tags": [ ],
  	"paths": {
		"<http method type>" : {
        			"tags": [ ],
                                "summary": " ",
                                "description": " ",
                                "operationId": "<unique operation id>",
                                "parameters":[ ],
        			"requestBody": { },
                                "responses": { }
		}
  	}
}

This structure forces to have single method of its kind per path which is not suitable when there are multiple operations of same method type that can be performed on the single path. Openapi 3.0.0 gives us the option of using oneOf in both request body and responses but does not provide a query parameter overloading or scenario where there are two required query parameters that are mutually exclusive. Regardless of anything mentioned above restricting single method type for each path puts restrictions on lot of real world api uses cases from being handled.

Two ways to resolve, changes that I'm suggesting:

1. Given openapi specification requires operationId to be unique throughout the spec file we can use it one layer below the path itself instead of method types to provide possibility of using multiple operations for same method under same path.

{
  	"openapi": "3.0.0",
  	"servers": [ ],
  	"info": { },
  	"tags": [ ],
  	"paths": {
		"<unique operation id>" : {
        			"tags": [ ],
                                "summary": " ",
                                "description": " ",
                                "method": "<http method type>",
                                "parameters":[ ],
        			"requestBody": { },
                                "responses": { }
		}
  	}
}

or

2. we can provide operations with same method type as an array to the method type key

{
  	"openapi": "3.0.0",
  	"servers": [ ],
  	"info": { },
  	"tags": [ ],
  	"paths": {
		"<http method type>" : [
  			{
        			"tags": [ ],
                                "summary": " ",
                                "description": " ",
                                "operationId": "operation 1",
                                "parameters":[ ],
        			"requestBody": { },
                                "responses": { }
  			},
  			{
        			"tags": [ ],
                                "summary": " ",
                                "description": " ",
                                "operationId": "operation 2",
                                "parameters":[ ],
        			"requestBody": { },
                                "responses": { }
  			}
		]
  	}
}

Related Issues:
#182
#791
#298
#868
#1500

[darrelmiller]

operationId is not a first class HTTP concept and therefore shouldn't be used to distinguish between logical operations. If we are to allow query parameters to discriminate between logical operations then we need to promote query parameters up into the "paths" keys. That makes "paths" the wrong name but conceptually that's where the differentiation should be made.

We have discussed this in the past and there are a number of people who would like to see this capability added. However, currently this is one of the few remaining opinionated parts of OpenAPI. Today only the path portion of the URL can define the operation.