SpringBoot项目中替换Swagger UI下拉菜单的问题咨询

1. WrapComponents插件方式可能遗漏的关键点 #

以下是常见的配置错误点，你可以逐一排查：

• 组件名称大小写错误：Swagger UI暴露的React组件是TopBar（首字母大写），如果你的代码里写的是topbar或其他小写形式，肯定不会生效。
• 插件注册不正确：自定义插件必须是一个返回包含wrapComponents对象的函数，并且要在SwaggerUIBundle的plugins数组中传入这个函数（不是函数调用后的结果）。
• React元素返回不规范：测试时返回的hello world必须包裹在有效的React元素中（比如<div>），不能直接返回纯文本字符串。
• 脚本加载顺序错误：自定义插件的JS文件必须在Swagger UI的核心脚本（swagger-ui-bundle.js、swagger-ui-standalone-preset.js）之后加载，否则无法获取到SwaggerUIBundle对象。
• 版本兼容性问题：确认你使用的Swagger UI版本支持wrapComponents钩子，OpenAPI 3.0对应的Swagger UI版本建议在3.0.0以上，部分旧版本可能没有这个钩子。

附上正确的插件示例代码：

// 自定义TopBar插件
const customTopBarPlugin = () => {
  return {
    wrapComponents: {
      TopBar: (OriginalComponent) => (props) => {
        // 测试用：完全替换TopBar为hello world
        return <div style={{padding: '10px'}}>hello world</div>;
        
        // 如果需要保留TopBar其他元素，仅替换下拉菜单：
        // return (
        //   <OriginalComponent {...props}>
        //     {/* 移除原下拉，插入自定义ul/li菜单 */}
        //     <ul className="custom-api-menu">
        //       <li><a href="/v3/api-docs">API Docs (JSON)</a></li>
        //       <li><a href="/v3/api-docs.yaml">API Docs (YAML)</a></li>
        //     </ul>
        //   </OriginalComponent>
        // );
      }
    }
  };
};

// 初始化Swagger UI
window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "/v3/api-docs",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [customTopBarPlugin], // 这里传入插件函数
    layout: "StandaloneLayout"
  });
  window.ui = ui;
};

2. 非插件实现方式 #

如果不想用插件，有两种可行方案：

方案一：DOM替换+MutationObserver监听 #

利用原生JS修改DOM，同时监听Swagger UI的渲染变化，避免React重渲染覆盖你的修改：

document.addEventListener('DOMContentLoaded', () => {
  // 监听Swagger UI容器的DOM变化
  const observer = new MutationObserver((mutations) => {
    mutations.forEach(() => {
      const originalDropdown = document.querySelector('.swagger-ui .topbar .download-url-wrapper');
      if (originalDropdown && !document.querySelector('.custom-api-menu')) {
        // 创建自定义ul/li菜单
        const customMenu = document.createElement('ul');
        customMenu.className = 'custom-api-menu';
        customMenu.innerHTML = `
          <li style="display: inline-block; margin: 0 10px;">
            <a href="/v3/api-docs" style="color: #fff;">JSON</a>
          </li>
          <li style="display: inline-block;">
            <a href="/v3/api-docs.yaml" style="color: #fff;">YAML</a>
          </li>
        `;
        // 替换原下拉菜单
        originalDropdown.parentNode.replaceChild(customMenu, originalDropdown);
      }
    });
  });

  observer.observe(document.getElementById('swagger-ui'), {
    childList: true,
    subtree: true
  });
});

方案二：修改Swagger UI源码 #

下载Swagger UI的官方源码，找到src/core/components/TopBar.jsx文件，直接修改其中的下拉菜单部分为ul/li结构，然后重新打包静态资源，替换项目中依赖的Swagger UI文件。这种方式适合深度定制，但缺点是后续Swagger UI版本升级时需要重新修改代码，维护成本较高。

内容的提问来源于stack exchange，提问作者Oscar Quebec