讯享网

                            <p>当项目中存在多个模块或多个版本的接口时，使用 <strong>Swagger 接口分组</strong>功能可以更好地组织和管理这些接口。例如，一个项目中有用户模块、订单模块和产品模块，我们可以使用接口分组将这些接口进行分组，使得文档更加清晰和易于查找。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-124.png" class="kg-image" alt="Swagger 接口分组配置教程" loading="lazy" width="1280" height="676" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-124.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-124.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-124.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Swagger</figcaption></figure><p></p><p>在 Swagger 中，我们可以通过添加  注解来配置接口分组。这个注解需要添加在控制器类上，用于表明该控制器属于哪个分组。在注解中，我们可以指定分组的名称和描述信息。也可以在 Swagger 配置文件中（如 SwaggerConfig.java 或 SwaggerConfig.xml）添加多个 Group 对象，每个 Group 对象表示一个分组。<br><br></p><p>以下是一个可以在 Swagger Editor 中运行的 Swagger 分组的实践案例：</p><pre></pre><p>这个例子定义了一个名为 E-commerce API 的 Swagger 文档，并进行了分组。在标签（tags）部分定义了两个分组：Products 和 Orders。每个分组下面分别有对应的接口，用于管理商品和订单。</p><p><br>你可以将上述代码复制到 Swagger Editor 中，即可查看 API 文档的可视化界面。在"Tags"栏中可以选择不同的分组，看到对应的接口和数据模型。并且可以根据定义的接口和数据模型进行测试和调试。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-125.png" class="kg-image" alt="Swagger Editor 中的分组示例" loading="lazy" width="1280" height="662" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-125.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-125.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-125.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Swagger Editor 中的分组示例</figcaption></figure><p></p><p>假设我们正在用 SpringBoot 构建一个电商网站的后端接口，其中包含商品管理和订单管理两个模块。我们可以使用 Swagger 分组来管理这两个模块的接口。<br></p><ol><li>首先，在 Swagger 配置文件中定义两个分组：</li></ol><pre></pre><p><br>在这个例子中，我们定义了两个分组："商品管理"和"订单管理"。分别指定了对应模块的包路径。</p><p><br>2. 在接口中使用@Api 注解指定接口所属的分组：</p><pre></pre><p>在这个例子中，我们在 ProductController 和 OrderController 的类上使用了@Api 注解，指定了它们所属的分组。<br></p><p>3. 启动项目后可以访问不同分组的接口文档：</p><ul><li>商品管理模块的接口文档：http://localhost:8080/swagger-ui.html#/商品管理</li><li>订单管理模块的接口文档：http://localhost:8080/swagger-ui.html#/订单管理<br>通过访问不同路径可以访问不同分组的接口文档。<br><br></li></ul><p>使用接口分组功能时，需要注意以下几点：</p><ol><li>分组名称应该简明扼要，能够准确描述该组接口的用途。</li><li>每个控制器类仅能属于一个分组，但可以在一个控制器类中包含多个接口。</li><li>注意避免重复的分组名称，以免混淆和误解。<br></li></ol><ol><li><strong>为什么接口没有分组显示？</strong></li></ol><p> 确保每个控制器类都添加了  注解，并指定了正确的分组名称。</p><p><strong>2. 如何更改接口分组的显示顺序？</strong></p><p> 可以通过在  注解中指定  属性来指定分组的显示顺序，数值越小越靠前。<br><br></p><p>Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-126.png" class="kg-image" alt="Apifox 的 IDEA 插件" loading="lazy" width="1280" height="834" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-126.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-126.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-126.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Apifox 的 IDEA 插件</figcaption></figure><p>Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + <strong>Swagger</strong> + Mock + JMeter，Apifox 支持调试 http（s）、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。</p><p><br>Apifox 的 IDEA 插件可以自动解析代码注释，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不切换工具的情况下将他们的文档与 Apifox 项目同步。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-127.png" class="kg-image" alt="Apifox Helper" loading="lazy" width="1280" height="755" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-127.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-127.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-127.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Apifox Helper</figcaption></figure><p><br><strong>当在 IDEA 项目中有接口信息变动，只需右键点击「 Upload to Apifox」一键即可完成同步，无需奔走相告。</strong>团队成员可在 Apifox 中看到同步后的最新内容。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-128.png" class="kg-image" alt loading="lazy" width="850" height="503" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-128.png 600w, https://apifox.com/apiskills/content/images/2023/10/image-128.png 850w" sizes="(min-width: 720px) 720px"><figcaption>Apifox 的 IDEA 插件一键同步接口</figcaption></figure><p><br>现在出发去 JetBrains 插件市场 下载试试吧！或直接在 IDEA 内 「plugin」入口直接搜索 <strong>Apifox Helper</strong>。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-129.png" class="kg-image" alt="Apifox 的接口调试界面" loading="lazy" width="1280" height="810" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-129.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-129.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-129.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Apifox 的接口调试界面</figcaption></figure><p><strong><em>知识扩展：</em></strong></p><ul><li><strong><em>Swagger map 类型参数使用详解</em></strong></li><li><strong><em>Swagger 中接口如何排序？</em></strong></li></ul><p><br><br><br><em><strong>参考链接：</strong></em></p><ul><li><em>官方文档：https://swagger.io/docs/specification/api-grouping/</em></li><li><em>Springfox( Swagger for Spring Boot) : https://springfox.github.io/springfox/docs/current/</em></li></ul>