Feedback on `operationPath`

[RomanHotsiy]

Hey folks 🙌 !

I've noticed you added support for operationPath for ability to target operations without operationId using JSON Pointer.

I have some feedback based on our experience working with this kind of format (JSON Pointer).

We have our users constantly confused about the correct format for the pointer:

• they either forget to escape pointers at all #/paths/pet/findByStatus/get
• they realize they need to escape the JSON pointer but they miss the leading slash: #/paths/pet~1findByStatus/get

What we ended up using is to use separate values for path and HTTP verbs. In our WIP implementation we added support for:

x-operation:
  sourceDescription: petStoreDescription # optional if only one sourceDescription is defined
  path: /pet/findByStatus
  method: get

I think this approach should work for the future versions of OpenAPI too. What do you think about it? I can open PR with adjustments if you like it!

[frankkilcommins]

Hi @RomanHotsiy,

I take your point, but RFC 6901 is pretty clear as to the escaping and evaluation rules.

If users really struggle in being able to specify the pointers then the first port of call should be to decorate their APIs with operationId negating the need to utilize operationPath.

The proposals moving forward in future versions of OpenAPI (a.k.a. Moonwalk) will enforce operationId by having it as a key under the Requests Object.

If it's something you want to utilize, then I would suggest you continue to do so via an extension.

[adamaltman]

What about making the operationPath an extension so that tooling providers can decide whether or not to implement it? It would encourage more use of operationId and make APIs "more ready" for Moonwalk.

It has a side-benefit of not needing to explain mutual exclusivity in the spec.

[frankkilcommins]

My concern with transferring operationPath to an extension is that it could be overlooked by the majority of implementors, causing interoperability issues across tool chains. This could undermine the ability of the specification to work consistently with the current API descriptions of many APIs that currently lack an operationId.

As it stands, operationPath is optional. Therefore, implementors who choose not to support operationPath can opt out and should clearly state in their documentation that they require operationId. This approach can be undertaken with the understanding that their user base is prepared to accommodate this requirement.