如何 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 编辑器不支持此类永久链接。
我正在为未来 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 编辑器不支持此类永久链接。