如何在OpenAPI / Swagger中指定递归路径

Question

我想为我的Swagger API创建一个递归规范。 the Swagger documentation似乎没有这个概念，所以我怀疑这是不可能的。因此，我也对Swagger支持的任何替代解决方案持开放态度。

例如，我尝试创建类似文档的结构。每个文档都有部分，每个部分都有文本和自己的部分。 我计划使用这样的API端点：

• http://a.b.com/docs/ {文档ID}
• http://a.b.com/docs/ {文档ID} /部分/ {段-ID}
• http://a.b.com/docs/ {文档ID} /部分/ {段-ID} /部分/ {段-ID}
• http://a.b.com/docs/ {文档ID} /部分/ {段-ID} /部分/ {段-ID} /部分/ {段-ID}

如果我使用正则表达式，我会在API规范中使用类似的东西：

...    
paths:
    /docs/{document-id}:
        get:
          ...
    /docs/{document-id}(/section/{section-id))+:
        get:
          ...

所以问题是：

1. 如何在Swagger / OpenAPI规范中表示任意嵌套资源
2. 是否有替代方法可以消除递归规范的需要？

Answer 1

我建议使用更简单的API设计。在某些公司中，限制最多为2个路径参数。还有更多，你正在推动可用性的限制。