Как связаться с другой конечной точкой в ​​Swagger - PullRequest
Новая
       47

Как связаться с другой конечной точкой в ​​Swagger

0 голосов
/ 08 октября 2018

Я пишу спецификацию Swagger для будущего общедоступного API, которая требует очень подробной и чистой документации. Есть ли способ указать / связать / указать другую конечную точку в каком-то другом месте в файле swagger.yml ?

Например, вот что япытаясь достичь: 

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:
        ...

Я обнаружил, что $ref не помогает, потому что он просто заменяет собой содержимое ссылки.

Может ли Swagger сделать такую ​​вещь?

1 Ответ

0 голосов
/ 08 октября 2018

Swagger UI предоставляет постоянные ссылки для тегов и операций, если он настроен с параметром deepLinking: true.Эти постоянные ссылки генерируются на основе имен тегов и operationId (или, если нет operationId - на основе имен конечных точек и глаголов HTTP). 

index.html#/tagName
index.html#/tagName/operationId

Вы можете использовать эти постоянные ссылки в вашей уценкеразметка: 

      description: >
        This endpoint does things.
        See [/my/otherEndpoint](#/tagName/myOtherEndpointId) for stuff

Примечания:

  • Ссылки уценки (как указано выше) в настоящее время открываются в новой вкладке браузера (как с target="_blank").
  • Ссылки в формате HTML <a href="#/tagName/operationId">foobar</a> в настоящее время не работают .
  • Редактор Swagger не поддерживает такие постоянные ссылки.
...