How to link to another endpoint in Swagger
Swagger UI provides permalinks for tags and operations if it's configured with the deepLinking: true
option. These permalinks are generated based on the tag names and operationId
(or if there are no operationId
- based on the endpoint names and HTTP verbs).
index.html#/tagName
index.html#/tagName/operationId
You can use these permalinks in your Markdown markup:
description: >
This endpoint does things.
See [/my/otherEndpoint](#/tagName/myOtherEndpointId) for stuff
Notes:
- Markdown links (such as above) currently open in a new browser tab (as with
target="_blank"
) - see issue #3473. - HTML-formatted links
<a href="#/tagName/operationId">foobar</a>
currently don't work. - Swagger Editor does not support such permalinks.
Related videos on Youtube
AdrienW
BY DAY: Backend software developer BY NIGHT: Mathematics enthusiast "The question of whether machines can think is about as relevant as the question of whether submarines can swim" - Edsger Wybe Dijkstra
Updated on June 23, 2022Comments
-
AdrienW almost 2 years
I'm writing a Swagger specification for an future public API that requires a very detailed and clean documentation. Is there a way to reference/link/point to another endpoint at some other location in the swagger.yml file?
For example, here is what I am trying to achieve:
paths: /my/endpoint: post: tags: - Some tag summary: Do things description: > This endpoint does things. See /my/otherEndpoint for stuff # Here I would like to have some kind of hyperlink operationId: doThings consumes: - application/json produces: - application/json parameters: ... responses: ... /my/otherEndpoint: # This is the endpoint to be referenced to get: ...
I have found that
$ref
does not help because it simply replaces itself with the contents of the reference.Can Swagger do such a thing?
-
Helen over 5 yearsWhich tool do you use to render the documentation - Swagger UI or something else?
-
AdrienW over 5 yearsRight now I'm working with editor.swagger.io but the API will use Swagger UI
-
AdrienW over 5 years@jvoigt I need to have references to endpoints in description fields (text) so this does not help me, but thanks!
-
-
savinaya over 2 years