yaml - How to link to another endpoint in Swagger

Question

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?

Answer 1

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.