Swager:通配符路径参数

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

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

这是Connexion的一个例子。

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

不同之处在于添加了格式：路径。

Answer 2

从OpenAPI 3.1开始，这是不受支持的，我不得不求助于一种解决方法。

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

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