如何链接到 Swagger 中的另一个端点 [英] How to link to another endpoint in Swagger

问题描述

我正在为未来的公共 API 编写 Swagger 规范，该规范需要非常详细和清晰的文档.有没有办法在 swagger.yml 文件中的其他位置引用/链接/指向另一个端点?

I'm writing a Swagger specification for an future public API that requires a very detailed and clean documentation. Is there a way to reference/link/point to another endpoint at some other location in the swagger.yml file?

例如，这是我想要实现的目标:

For example, here is what I am trying to achieve:

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 没有帮助，因为它只是用引用的内容替换了自己.

I have found that $ref does not help because it simply replaces itself with the contents of the reference.

Swagger 能做这样的事情吗?

Can Swagger do such a thing?

推荐答案

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

Swagger UI provides permalinks for tags and operations if it's configured with the deepLinking: true option. These permalinks are generated based on the tag names and operationId (or if there are no operationId - based on the endpoint names and HTTP verbs).

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

您可以在 Markdown 标记中使用这些固定链接:

You can use these permalinks in your Markdown markup:

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

注意事项:

• Markdown 链接(如上述)当前在新的浏览器标签页中打开(如 target="_blank") - 请参阅 issue #3473.
• HTML 格式的链接 foobar 当前 不起作用.
• Swagger Editor 不支持此类固定链接.

这篇关于如何链接到 Swagger 中的另一个端点的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！