Swagger UI 中的多级（嵌套）标记

Question

我最近才开始研究 Swagger 2.0 API。我正在寻找一些方法来组织 API 文档。

目前我正在使用@Api(tags = {"Heading1"}) Java 注释来标记每个 API。生成的文档看起来像

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