如何配置Quarkus加载@kael-shipman/swagger-ui-plugin-hierarchical-tags插件

要让Quarkus正确加载这个Swagger UI分层标签插件，需要完成两个核心步骤：引入插件脚本、配置插件标识，具体操作如下：

1. 引入插件脚本 #

Quarkus无法直接识别npm包名，需要先确保插件的JS脚本能被Swagger UI页面加载，有两种方式可选：

方式一：通过npm集成（推荐，适用于Quarkus 3.x+） #

• 首先在项目根目录执行npm安装命令：

  npm install @kael-shipman/swagger-ui-plugin-hierarchical-tags
  

• 确保Quarkus启用了npm静态资源支持（使用Quarkus Web或Reactive Web扩展时默认已支持）。

方式二：手动添加脚本文件 #

• 从插件的分发包中下载打包好的脚本文件（比如hierarchical-tags-plugin.min.js）；
• 将文件放到项目的src/main/resources/META-INF/resources目录下，Quarkus会自动识别该目录下的静态资源。

2. 配置Quarkus参数 #

在application.properties中添加以下配置：

# 配置要加载的插件脚本路径
quarkus.swagger-ui.additional-scripts=node_modules/@kael-shipman/swagger-ui-plugin-hierarchical-tags/dist/hierarchical-tags-plugin.min.js
# 配置插件的全局变量名（插件导出的标识）
quarkus.swagger-ui.plugins=HierarchicalTagsPlugin

如果你用的是手动添加脚本的方式，将additional-scripts的值改为你放置的脚本文件名，比如hierarchical-tags-plugin.min.js

3. 验证配置 #

启动Quarkus应用，访问/swagger-ui页面，检查API标签是否按照层级结构显示，以此确认插件是否生效。

常见问题排查 #

• 如果插件不生效，先检查浏览器控制台是否有脚本加载错误，确认脚本路径配置正确；
• 确认Quarkus的quarkus-swagger-ui依赖的Swagger UI版本与插件兼容（该插件支持Swagger UI 4.x，Quarkus 3.x系列对应的Swagger UI版本符合要求）；
• 你之前尝试的第三种配置HierarchicalTagsPlugin是正确的插件标识，但缺少了脚本加载的关键步骤，这是导致插件未生效的核心原因。

内容的提问来源于stack exchange，提问作者Charlie Walker