如何链接到Swagger中的另一个 endpoints-Java 学习之路

我正在为未来的公共API编写Swagger规范，需要非常详细和干净的文档 . Is there a way to reference/link/point to another endpoint at some other location in the swagger.yml file?

例如，以下是我想要实现的目标：

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能做这样的事吗？

1 回答

2
如果标签和操作配置了 deepLinking: true 选项，则Swagger UI会为其提供permalinks . 这些永久链接是基于标记名称和 operationId （或者如果没有 operationId - 基于 endpoints 名称和HTTP谓词）生成的 .
```
index.html#/tagName
index.html#/tagName/operationId
```
您可以在Markdown标记中使用这些永久链接：
```
description: >
        This endpoint does things.
        See [/my/otherEndpoint](#/tagName/myOtherEndpointId) for stuff
```
笔记：
- Markdown链接（例如上面）当前在新的浏览器选项卡中打开（与 target="_blank" 一样） .
- HTML格式的链接 <a href="#/tagName/operationId">foobar</a> 目前don't work .
- Swagger Editor不支持这样的永久链接 .
回复于 2024-05-05T12:06:27+08:00

如何链接到Swagger中的另一个 endpoints

1 回答

相关问题