如何链接到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选项进行配置，则会为标签和操作提供permalinks。这些永久链接是基于标记名称和operationId生成的（或者如果没有operationId-基于端点名称和HTTP谓词）。

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

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

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

注意：

• 降价链接（例如上面的链接）当前在新的浏览器标签中打开（与target="_blank"一样）。
• HTML格式的链接<a href="#/tagName/operationId">foobar</a>当前don't work。
• Swagger编辑器不支持此类永久链接。