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

Question

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

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

• http://a.b.com/docs/ {文件编号}
• http://a.b.com/docs/ {document-id}/section/{section-id}
• http://a.b.com/docs/ {document-id}/section/{section-id}/section/{section-id}
• http://a.b.com/docs/ {document-id}/section/{section-id}/section/{section-id}/section/{section-id}

如果我使用正则表达式样式，我会在 API 规范中使用类似这样的内容:

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

所以问题是:

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

Answer 1

我建议使用更简单的 API 设计。在某些公司中，限制是最多 2 个路径参数。任何更多，您都在插入可用性的极限。