Feature Request: support operationRef or operationId references in the fragment identifier

[mjpieters]

Please support operationId:<opId> and operationRef:<opRef> as additional fragment identifiers to move the view to a specific operation. I believe that this could be implemented with a hashchanged event handler.

• document#operationId:<opId> would scroll to the operation with operationId set to opId.
• document#operationRef:<opRef> would scroll to the operation at the specific reference path. This would be limited to #/paths/<encodedPath>/<operationName>, or possibly just <encodedPath>/<operationName> as the #/paths/ component of the path is implied in the operationRef: prefix, and there is no real option to support relative paths here.

Examples for the Petshop demo document would be:

• https://redocly.github.io/redoc/#operationId:getPetById
• https://redocly.github.io/redoc/#operationRef:#/paths/~1pet~1{petId}/get

Both would end up at the same location as the #operation/getPetById anchor.

motivation

We would like to reliably deeplink, from markdown documentation within the API or from other locations, to the operations an API document regardless of the OpenAPI renderer used.

Currently, ReDoc will generate anchors for a given operation, in one of two forms:

• if the operationId key is set: operation/{operationId}
• otherwise: tags/{tagName}/{operationRef}/, where the operationRef is relative to the document root (not prefixed with #/paths/... but with paths/). I am assuming that the tagName used is the first registered tag listed in the operation tags list.

You can use these anchor identifiers as fragment identifiers in the URL (../#operation/getPetById), and so you can link to these from Markdown too.

However, these paths are very specific to ReDoc, even though they have a direct relationship to the OpenAPI specification rendering of the doc. Relying on this by explicitly using the same format in markdown links feels like we'd be relying on implementation details.

existing OpenAPI discussion

I see that there is a [related discussion on the OAI spec repository, where there is a proposal to have an OpenAPI documentation to explicitly document how operationIds and operationRefs could be used as fragment identifiers.

[DavidBiesack]

in particular, injecting the sluggified version of the operation's tags into the anchor name ( #tag/Sluggified-Tag-Text/operation/operationId makes this harder and is not necessary. One should be able to reference the section for an operation using just the operation ID and not know the tag (and not know how ReDoc converts tag names to anchor slugs)