如何配置独立Swagger UI仅显示特定端点以生成多页API文档？

核心解决思路 #

Swagger UI自带的filter仅提供搜索筛选功能，无法默认隐藏非目标端点。要实现拆分文档、仅展示特定端点，可通过以下三种方式实现：

方法一：预处理OpenAPI规范文件 #

直接修改原始OpenAPI定义文件，按业务模块拆分：

• 复制原始的openapi.yaml/openapi.json，分别命名为api-users.yaml、api-orders.yaml等
• 逐个删除文件中不需要的paths节点下的端点
• 为每个处理后的文件单独部署Swagger UI实例，或者在同一页面通过切换加载不同文档

方法二：自定义Swagger UI初始化逻辑（无需修改原始文件） #

在Swagger UI的初始化脚本中，加载原始规范后手动过滤端点：

<script>
// 加载原始OpenAPI规范文件
fetch('/openapi.json')
  .then(res => res.json())
  .then(spec => {
    // 定义当前页面需要保留的端点路径
    const allowedPaths = ['/users', '/users/{id}', '/users/profile'];
    
    // 过滤paths对象，仅保留允许的端点
    const filteredPaths = Object.fromEntries(
      Object.entries(spec.paths).filter(([path]) => allowedPaths.includes(path))
    );
    
    // 更新规范中的paths节点
    spec.paths = filteredPaths;
    
    // 初始化Swagger UI
    window.ui = SwaggerUIBundle({
      spec: spec,
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ]
    });
  });
</script>

方法三：用urls配置实现同实例多文档切换 #

如果希望在同一个Swagger UI里切换不同模块的文档，可配置urls参数，每个条目对应一个预处理后的文档：

<script>
window.ui = SwaggerUIBundle({
  urls: [
    { url: '/api-users.json', name: '用户管理API' },
    { url: '/api-orders.json', name: '订单管理API' },
    { url: '/api-products.json', name: '商品管理API' }
  ],
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ]
});
</script>

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