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

问题描述 投票：0回答：3
我想在文档中添加一些子标题，以便看起来像

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

我如何实现？

OpenAPI规范不支持``钉住标签''。这是相应的功能请求：

https：//github.com/oai/openapi-specification/issues/1367

您可以通过命名标签
tag1/tag2
，


swagger

swagger-ui

openapi

swagger-2.0


3个回答




    
    
    

        

            

                

                    
24
投票

                    
                

            

        

        
，
tag1|tag2
或类似方法来模拟嵌套的标签，但是您还必须修改工具以处理诸如嵌套标签的名称。
swagger UI用户注：有一个功能请求，可以使用表单或类似形式中的标签名称支持嵌套标签：
https：//github.com/swagger-api/swagger-ui/issues/5969

    

Helen的答案正确地指出，目前在没有插件的情况下就无法摇摇晃晃（请参阅我的其他答案）或VanillaOpenapi.
。

，swagger替代
雷德（Redoc）介绍并实现了一个名为
tag1|tag2

    

    
    
    

    

        

            

                

                    
3
投票

                    
                

            

        

        
的Openapi扩展名，顾名思义，您可以将标签组合在一起。这使您可以在标签上方介绍
一个其他嵌套级别，但不再是。

不过，一个警告词：截至2024年，redoc缺乏大大的特征，例如“尝试”功能或能够显示请求和响应模型名称。此外，REDOC构成了付费产品的开放核心（重新计算），该产品实现了其中的一些功能，因此这些功能不太可能会陷入重建，因为这会与他们的业务模型冲突。因此，这不是Swagger的替代者。
    


在Helen的答案中链接的sissue的创建者创建了一个称为
x-tagGroups
的插件。我只会引用示例Swagger UI HTML文件，来自theme：：


swagger-ui-plugin-hierarchical-tags
having以这种方式设置了Swagger UI，您可以在标签名称中使用
<!doctype html>
<html>
  <head>
    <!-- Load Swagger UI -->
    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script> 

    <!-- Load the HierarchicalTags Plugin -->
    <script src="https://unpkg.com/swagger-ui-plugin-hierarchical-tags"></script>

    <!-- Load styles -->
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />

    <script>
      window.onload = function() {
        SwaggerUIBundle({
          url: "https://unpkg.com/swagger-ui-plugin-hierarchical-tags/example/pet-store.json",
          dom_id: "#swagger",
          plugins: [
            HierarchicalTagsPlugin
          ],
          hierarchicalTagSeparator: /[:|]/
        })
      }
    </script>
  </head>
  <body>
    <div id="swagger"></div>
  </body>
</html> 


    

    
    
    

    

        

            

                

                    
2
投票

                    
                

            

        

        
hierarchicalTagSeparator
的标签将是一个名为MyTopic: MySubtopic: MyTag的标签，该标签又是名为MyTag的组，该标签又是在
MySubtopic
中分组的标签。
    
	


    

    


  

  

    
最新问题


  





  

    © www.soinside.com 2019 - 2025. All rights reserved.