如何 link 到 Swagger 中的另一个端点

How to link to another endpoint in Swagger

我正在为未来 public API 编写 Swagger 规范,它需要非常详细和干净的文档。 有没有办法 reference/link/point 到 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能做这样的事吗?

Swagger UI 为标签和操作提供 如果它配置了 deepLinking: true 选项。这些永久链接是根据标签名称和 operationId 生成的(或者如果没有 operationId - 基于端点名称和 HTTP 动词)。

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

您可以在 Markdown 标记中使用这些永久链接:

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

备注:

  • Markdown 链接(如上)当前在新的浏览器选项卡中打开(与 target="_blank" 一样)- 请参阅 issue #3473
  • HTML 格式的链接 <a href="#/tagName/operationId">foobar</a> 目前 don't work
  • Swagger 编辑器不支持此类永久链接。