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

Question

我想为我的Swagger API创建一个递归规范。这个概念似乎没有出现在Swagger文档中，所以我怀疑这是不可能的。因此，我也愿意接受任何由Swagger支持的替代解决方案。

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

• 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/{文件编号}/节/{节号编号}/节/{节号编号}/节/{节号编号}

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

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

所以问题是：

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

Answer 1

我建议使用更简单的API设计。在一些公司中，限制最多为2个路径参数。只要你做得更多，你就会突破可用性的极限。