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

Posted 2023-02-26

【中文标题】如何链接到 Swagger 中的另一个端点

【英文标题】：How to link to another endpoint in Swagger

【发布时间】：2019-03-13 05:10:08

【问题描述】：

我正在为未来的公共 API 编写 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 能做这样的事吗？

【问题讨论】：

您使用哪种工具来呈现文档 - Swagger UI 或其他工具？

现在我正在使用editor.swagger.io，但 API 将使用 Swagger UI

查看 YAML 原生锚点：blog.daemonl.com/2016/02/yaml.html

@jvoigt 我需要在描述字段（文本）中引用端点，所以这对我没有帮助，但是谢谢！

【参考方案1】：

如果配置了 deepLinking: true 选项，Swagger UI 会为标签和操作提供 permalinks。这些永久链接是根据标签名称和 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 编辑器不支持此类永久链接。

【讨论】：

对，这取决于我们用来渲染 openapi 文档的工具。就我而言，我使用的是RapiDoc。对于带有“发送消息”标签的 API，我们可以将链接指定为 this -> [Send Message](#tag--send-message)。 more info