Add option to show operationId

[marclave]

Discussed in #1209

Originally posted by ninanator March 15, 2024

Feature Request

I would like to be able to show the operationId in the UI. This will allow developers who use auto-generated clients to be able to quickly reference the operationId, since that it is how they know the endpoint. Since this is more of a niche request, I think it would be fair to make this an optional value that can be toggled at the client level.

Examples

Swagger UI

See: https://petstore.swagger.io/?displayOperationId=true

Redocly

See: https://redocly.com/docs/openapi/petstore/pet/uploadFile/

Readme.io

See: https://pet-store-api-explorer.readme.io/reference/uploadfile

Proposed Positioning

I think, based on the other elements already on the page, that this location would be the least disruptive. It could be above the description value and potentially italicized.

Thank you!

[aditya-67]

@marclave I see that endpoints in the Sidebar are referenced via a combination of tags, method and path like this #tag/{tagName}/{method}/{path}.

I'm just curious to understand more on the decision to use tags in the URLs.

Could this use the operationID directly in the URL, #operation/{operationID}? If operationID is not present, we use a combination path and method like this #path/{path}/{method} to maintain uniqueness. Attaching some screenshots for reference.

I think it can be much easier to access an API endpoint via an operationID, given the uniqueness of it. More context here

Please let me know your thoughts on this

[marclave]

@aditya-67 really sorry I missed this!

I really appreciate your comment and all the added context.

@amritk thoughts on conditional router based on if operationId is present?

[amritk]

I think we should be able to do it, something like /operation/${id}. Will require some changes though

[arthurfiorette]

Hey! any updates on this?

[amritk]

Sorry @arthurfiorette not at the moment, @marclave what do you think?

[hanspagel]

I think we should even consider to make it the default, and the current way the fallback. 🤔

But it might take some time, as it touches quite a few places and would be a breaking change. Maybe something for a version 2.x?