Swagger：通配符路径参数

Question

我有一个 API 允许传入任意路径，例如所有这些：

/api/tags
/api/tags/foo
/api/tags/foo/bar/baz

是有效路径。我试着描述如下：

 /tags{tag_path}:
    get:
      parameters:
        - name: tag_path
          in: path
          required: true
          type: string
          default: "/"

但是，https://generator.swagger.io 对路径中的斜杠进行了编码，因此它不起作用。那么有没有办法在 Swagger 中描述我的 API？

Answer 1

从 OpenAPI 3.1 开始不受支持，我必须求助于解决方法。

如果我有一个路径 /tags{tag_path} 并且我输入这样的内容 tag_path: /foo/bar，那么实际的查询请求 URL 将是：/tags%2Ffoo%2Fbar.因此，我刚刚在我的后端添加了对此的支持：/tags* 的端点处理程序对路径（即 %2Ffoo%2Fbar）进行 url 解码，然后它再次变为 /foo/bar。

是的，一个黑客，但它有效，总比没有好。在我的例子中，标签名称不能包含 / 字符，所以没有冲突。当然，您的里程可能会有所不同。

Answer 2

如果您使用的是像 Connexion 这样的框架，它很可能支持通配符路径参数（即使它不在 OpenAPI 规范中）。

以下是 Connexion 的示例。

paths:
  /pages/{path}:
    get:
     # (...)
      parameters:
        - name: "path"
          in: path
          description: "Remainder of path, including slashes."
          schema:
            type: string
            format: path

区别在于添加了format: path。

Swagger：通配符路径参数

Swagger: wildcard path parameters

swagger

swagger-ui

swagger-2.0

openapi