将所有Node.js微服务Swagger链接合并为单个Swagger并部署的方法

当然有可行方案，以下是几种成熟的实现方式，可根据你的场景选择：

1. 利用Swagger UI原生的多文档聚合能力 #

Swagger UI本身支持加载多个独立的OpenAPI规范，只需在初始化时配置urls数组，就能在同一个UI界面中切换查看所有微服务的文档。

实现步骤： #

• 新建一个静态项目或简单Node.js服务，引入swagger-ui-dist依赖（通过npm install swagger-ui-dist安装）。
• 自定义Swagger UI的入口index.html，修改初始化配置：

  window.onload = function() {
    const ui = SwaggerUIBundle({
      urls: [
        { url: "http://your-service-ip:3001/swagger.json", name: "用户中心服务" },
        { url: "http://your-service-ip:3002/swagger.json", name: "订单管理服务" },
        { url: "http://your-service-ip:3003/swagger.json", name: "支付服务" }
      ],
      dom_id: '#swagger-ui',
      deepLinking: true,
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      layout: "StandaloneLayout"
    })
    window.ui = ui
  }
  

• 部署这个服务（可用Nginx托管静态文件，或用Express起简单服务），访问后就能看到顶部的文档切换下拉框，统一管理所有微服务的Swagger文档。

2. 通过API网关统一代理并聚合 #

搭建一个轻量API网关（比如用Express/Fastify），既代理微服务接口，又提供统一的Swagger入口，同时解决跨域和路由统一问题。

实现步骤（以Express为例）： #

• 初始化Express项目，安装依赖：npm install express http-proxy-middleware swagger-ui-express
• 配置代理规则，将网关路径映射到对应微服务：

  const { createProxyMiddleware } = require('http-proxy-middleware');
  const express = require('express');
  const app = express();
  
  // 代理微服务接口
  app.use('/api/user', createProxyMiddleware({ target: 'http://localhost:3001', changeOrigin: true }));
  app.use('/api/order', createProxyMiddleware({ target: 'http://localhost:3002', changeOrigin: true }));
  

• 配置统一Swagger UI入口，加载各微服务的Swagger文档：

  const swaggerUi = require('swagger-ui-express');
  const swaggerOptions = {
    urls: [
      { url: '/api/user/swagger.json', name: '用户中心服务' },
      { url: '/api/order/swagger.json', name: '订单管理服务' }
    ]
  };
  app.use('/swagger', swaggerUi.serve, swaggerUi.setup(null, swaggerOptions));
  
  app.listen(8080);
  

• 部署网关服务，访问http://网关IP:8080/swagger即可查看所有微服务的文档。

3. 离线合并OpenAPI规范后部署 #

如果微服务的Swagger文档变更不频繁，可以先将所有服务的OpenAPI文件合并成一个统一的规范文件，再部署单独的Swagger UI展示。

实现步骤： #

• 导出每个微服务的Swagger JSON/YAML文件。
• 使用openapi-merge-cli工具合并规范，先安装：npm install -g openapi-merge-cli
• 创建合并配置文件merge-config.json：

  {
    "inputs": [
      { "input": "./user-swagger.json", "pathModification": { "stripStart": "/api/user" } },
      { "input": "./order-swagger.json", "pathModification": { "stripStart": "/api/order" } }
    ],
    "output": "./combined-swagger.json"
  }
  

• 执行合并命令：openapi-merge-cli --config merge-config.json
• 用Swagger UI部署合并后的文件：

  const express = require('express');
  const swaggerUi = require('swagger-ui-express');
  const combinedDoc = require('./combined-swagger.json');
  const app = express();
  
  app.use('/swagger', swaggerUi.serve, swaggerUi.setup(combinedDoc));
  app.listen(8080);
  

注意事项： #

• 跨域处理：如果聚合服务和微服务不在同一域名，需在微服务端配置CORS，允许聚合服务域名访问Swagger接口。
• 版本同步：实时聚合方案（前两种）需确保微服务的Swagger接口稳定；离线合并方案需在文档更新后重新执行合并部署流程。

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