如何链接到 Swagger 中的另一个端点

Question

我正在为需要非常详细和干净的文档的未来公共 API 编写 Swagger 规范。有没有办法在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 可以做这样的事情吗？

Answer 1

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

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

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

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

笔记：

• Markdown 链接（如上）当前在新的浏览器选项卡中打开（如target="_blank"） - 请参阅问题 #3473。
• HTML 格式的链接<a href="#/tagName/operationId">foobar</a>目前不起作用。
• Swagger Editor 不支持此类固定链接。