Linking operations, tags, etc. from descriptions #1062
protyposis
started this conversation in
General
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Hi,
I'm looking for ideas on defining links in OpenAPI definition
description
fields to other operations and tags within the same definition, so that they render correctly with this plugin.Examples:
"After creating the resource with this endpoint, you can edit it with [operation x](/link/to/op-x) and list it with [operation y](...)."
groupPathsBy: 'tag'
), e.g.,"This property contains the ID of resource type Z. See related operations in section [tag z](/link/to/tag-z)."
The approach I found is building the documentation with this plugin, then manually copy them back into the OpenAPI definition. This obviously isn't ideal and potentially breaks when the configuration of Docusaurus or this plugin changes. (It's also incompatible with other tools like Redoc.) I couldn't find much discussion on this and am also wondering whether I am missing something obvious, or whether these kinds of links aren't widely used.
Ultimately it seems to me that this either requires a generic solution which works with all documentation generators, as discussed in the OpenAPI Spec repo and closed without a proper solution, or some sort of link transformation function within this plugin which allows converting some kind of generic link patterns to the final URLs in the generated documentation (which, as mentioned, vary depending on configuration).
How are other people handling this?
Beta Was this translation helpful? Give feedback.
All reactions