Make operationId mandatory

Hi, I would like to propose to make operationId required in Operation definition. As the specification states, this field may be used in tooling to uniquely identify operations. I have a couple of real world examples:

• different tools that support both http method/path combination have an algorithm that transforms the http method/path combination to an operationId, giving sometimes awful/unexpected results. For example, let’s say that you have a contract without operationIds and you generate clients for it using any tool. One day you update the contract changing a path name or a path parameter name. The generated clients will durely change the method names, while the meaning of the operation is always the same!
• Some libraries (like mine https://vertx.io/docs/vertx-web-api-contract/java/) uniquely refer to an operation using the operationId more than the http method/path combination. While the http method/path combination is subject to changes, while operationId usually remains related with the meaning of the operation.

In the end, I personally see operationId as the only meaningful operation identifier, that’s why I think we should encourage users to define it, making it mandatory

WDYT?

[MikeRalphson]

This issue is a dupe of closed issue #1019 (though that issue was closed by it’s original poster).

To summarise, the arguments against making operationId mandatory are:

• it would make document authoring more tedious and error-prone and probably increase the number of non-compliant documents in the wild
• making this property mandatory would likely not result in quality operationIds being used
• it is trivial to generate a missing operationId from the method and path, though perhaps not as readable
• if the method or path changes, is it really the same operation?
• alternative approaches such as using a uuid can be used where not intended for human consumption
• where necessary, document authors are likely to be already including this information
• this would be a breaking change and thus could not be considered until the OAS 4.x timeframe

This really leaves the case where a document author has not included operationIds but a third party requires them for a use-case such as code generation or framework ingestion. The proposed overlay approach in OAS 3.1 would likely be a reasonable way of resolving this issue.

First time I had an error for a lacking / duplicated operationId, it took time for me to handle the fact that the schema validator weren’t warning me on this.

A good OAS validator should definitely report an error on a duplicated operationId and several linters which use rules originated in oas-kit warn about missing operationIds by default.

[ahl]

Strong agreement from me. Our use of OperationId requires this for unique naming, through I can see how code or doc generation would not require it.