Swagger UI React带环境变量的DeepLinking滚动偏移问题求助

方案1：通过CSS设置锚点滚动偏移 #

直接利用CSS的scroll-margin-top属性，为API锚点元素添加偏移量，抵消服务器选择区域的高度：

/* 当页面存在服务器选择区域时，为API操作项的锚点设置滚动偏移 */
.swagger-ui .servers ~ .operations .operation-id {
  scroll-margin-top: 80px; /* 数值根据实际服务器区域高度调整，比如80px */
}

如果需要适配不同高度的服务器区域，也可以用CSS变量动态调整：

.swagger-ui .operation-id {
  scroll-margin-top: var(--scroll-offset, 0);
}

/* 检测到服务器区域时，设置偏移变量 */
.swagger-ui .servers {
  --scroll-offset: 80px;
}

方案2：监听Hash变化手动调整滚动位置 #

在React组件中监听hashchange事件，当深度链接触发时，计算服务器区域的高度并调整滚动位置：

import { useEffect } from 'react';

// 在渲染SwaggerUIReact的组件中添加
useEffect(() => {
  const adjustScroll = () => {
    const hash = window.location.hash;
    if (!hash) return;

    const targetEl = document.querySelector(hash);
    if (!targetEl) return;

    // 获取服务器选择区域的DOM元素
    const serversBar = document.querySelector('.swagger-ui .servers');
    const offset = serversBar ? serversBar.offsetHeight : 0;

    // 计算目标位置并滚动
    const targetPos = targetEl.getBoundingClientRect().top + window.pageYOffset - offset;
    window.scrollTo({ top: targetPos, behavior: 'smooth' });
  };

  // 初始加载和Hash变化时触发
  window.addEventListener('hashchange', adjustScroll);
  adjustScroll();

  return () => window.removeEventListener('hashchange', adjustScroll);
}, [openApiData]); // 依赖openApiData，确保切换API文档时重新执行

方案3：使用Swagger UI插件修正滚动行为 #

通过Swagger UI的插件机制，在深度链接触发时调整滚动偏移：

// 自定义插件
const ScrollFixPlugin = () => ({
  onDeepLink(event) {
    const { target } = event;
    if (!target) return;

    const serversSection = document.querySelector('.swagger-ui .servers');
    if (serversSection) {
      // 向上滚动抵消服务器区域的高度
      window.scrollBy(0, -serversSection.offsetHeight);
    }
  }
});

// 在SwaggerUIReact组件中引入插件
<SwaggerUIReact 
  spec={openApiData} 
  deepLinking={true} 
  docExpansion="list" 
  supportedSubmitMethods={['get', 'post', 'put', 'delete']}
  plugins={[ScrollFixPlugin]}
/>

方案选择建议 #

• 优先用CSS方案，实现简单无额外代码逻辑，适合固定高度的服务器区域
• 如果服务器区域高度动态变化，选择JS监听方案，能实时计算高度
• 追求Swagger UI原生扩展方式，用插件方案，更符合官方扩展规范

内容的提问来源于stack exchange，提问作者Muhammad Muiz Ather