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?

Which tool do you use to render the documentation - Swagger UI or something else? — Helen, Oct 08 '18 at 13:54
Right now I'm working with https://editor.swagger.io/ but the API will use Swagger UI — AdrienW, Oct 08 '18 at 14:01
check out YAML-native Anchors: https://blog.daemonl.com/2016/02/yaml.html — jvoigt, Oct 08 '18 at 15:09
@jvoigt I need to have references to endpoints in description fields (text) so this does not help me, but thanks! — AdrienW, Oct 08 '18 at 15:16

Helen · Accepted Answer · 2019-09-12T12:07:04.483

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.

right, it depends on the tool we use to render the openapi doc. In my case, I'm using [RapiDoc](https://mrin9.github.io/RapiDoc/). For 'send message' tagged API we can specify link as this -> [Send Message](#tag--send-message). [more info](https://mrin9.github.io/RapiDoc/examples/links) — savinaya, Jan 13 '22 at 10:42

How to link to another endpoint in Swagger

1 Answers1

Linked

Related