swagger - Swagger UI 中的多级(嵌套)标记

Question

我最近才开始研究 Swagger 2.0 API。我正在寻找一些组织 API 文档的方法。
目前我正在使用 @Api(tags = {"Heading1"})用于标记每个 API 的 Java 注释。生成的文档看起来像

Tasks
--------->Heading1
          -------->Desc1
          --------->Desc2
---------->Heading2
          --------->Desc3
          --------->Desc4

我想在文档中添加一些副标题，使其看起来像

Tasks
--------->Heading1
          -------->Desc1
          --------->SubHeading1
                        --------->Desc2
---------->Heading2
          --------->SubHeading1
                     --------->Desc3 
          --------->SubHeading1
                     --------->Desc4

我如何实现这一目标？

Answer 1

OpenAPI 规范不支持嵌套标签。这是相应的功能请求:
https://github.com/OAI/OpenAPI-Specification/issues/1367
您可以尝试通过命名标签来模拟嵌套标签 tag1/tag2 , tag1.tag2 , tag1|tag2或类似的，但是您还必须修改您的工具来处理诸如嵌套标签之类的名称。
Swagger UI 用户注意事项:有一个功能请求支持使用表单 tag1|tag2 中的标签名称的嵌套标签。或类似:
https://github.com/swagger-api/swagger-ui/issues/5969