如何从swagger-ui-dist服务端生成Swagger Docs的HTML字符串？

1. 安装依赖 #

先安装核心依赖包：

npm install swagger-ui-dist

2. 核心实现思路 #

swagger-ui-dist自带了基础的Swagger UI HTML模板，我们只需要读取该模板，替换其中的配置占位符，就能生成可自定义的HTML字符串。整个过程无需依赖Express或其他额外工具，纯Node.js+Fastify即可完成，完全符合KISS原则。

3. 完整代码示例 #

const fastify = require('fastify')({ logger: true });
const fs = require('fs');
const path = require('path');
// 获取swagger-ui-dist的绝对路径
const swaggerUiDistRoot = require('swagger-ui-dist').absolutePath();

// 预读取并缓存Swagger UI的基础HTML模板（仅需读取一次）
const baseSwaggerTemplate = fs.readFileSync(path.join(swaggerUiDistRoot, 'index.html'), 'utf8');

// 生成自定义Swagger HTML的工具函数
function buildSwaggerHtml(swaggerSource, uiOptions = {}) {
  // 构造Swagger UI初始化脚本
  const initScript = `
    window.onload = function() {
      SwaggerUIBundle({
        ${typeof swaggerSource === 'string' ? `url: "${swaggerSource}"` : `spec: ${JSON.stringify(swaggerSource)}`},
        dom_id: '#swagger-ui',
        ${Object.entries(uiOptions).map(([key, val]) => `${key}: ${JSON.stringify(val)}`).join(',\n        ')}
      });
    };
  `;

  // 替换模板中的默认初始化脚本，注入自定义配置
  return baseSwaggerTemplate.replace(/<script>window\.onload.*?<\/script>/s, `<script>${initScript}</script>`);
}

// Fastify路由：返回生成的Swagger HTML页面
fastify.get('/docs', async (req, reply) => {
  // 两种Swagger数据源可选：
  // 1. 接口地址（比如动态生成的Swagger JSON接口）
  const swaggerSource = '/swagger.json';
  // 2. 直接传入Swagger JSON对象（无需额外请求）
  // const swaggerSource = {
  //   openapi: '3.0.0',
  //   info: { title: 'My Fastify API', version: '1.0.0' },
  //   paths: { /* 接口定义 */ }
  // };

  // 自定义UI展示配置
  const uiConfig = {
    docExpansion: 'full', // 默认展开所有接口文档
    darkMode: true, // 启用深色主题
    defaultModelsExpandDepth: -1, // 隐藏Models面板
    persistAuthorization: true // 保留授权信息
  };

  const swaggerHtml = buildSwaggerHtml(swaggerSource, uiConfig);
  reply.type('text/html').send(swaggerHtml);
});

// 示例：提供Swagger JSON的路由（如果用接口地址作为数据源）
fastify.get('/swagger.json', async (req, reply) => {
  reply.send({
    openapi: '3.0.0',
    info: { title: 'My Fastify API', version: '1.0.0' },
    paths: {
      '/hello': {
        get: {
          summary: 'Say hello',
          responses: {
            '200': {
              description: 'Success',
              content: {
                'application/json': { schema: { type: 'object', properties: { message: { type: 'string' } } } }
              }
            }
          }
        }
      }
    }
  });
});

// 启动服务
fastify.listen({ port: 3000 }, (err) => {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }
});

4. 关键细节说明 #

• 模板缓存：预读取基础HTML模板并缓存，避免每次请求都读取文件，提升性能。
• 数据源灵活：支持传入Swagger JSON的接口地址，或直接传入JSON对象（无需额外HTTP请求）。
• UI自定义：uiConfig可传入所有Swagger UI支持的配置项，比如主题、文档展开方式、面板显示控制等。
• 缓存策略：如果Swagger配置不常变动，可将生成好的HTML字符串缓存到内存、文件或Redis中，进一步优化性能。

5. 方案优势 #

• 无额外依赖，仅使用核心包与Node.js API。
• 逻辑简单直接：读模板→替换配置→输出HTML，无复杂设计模式。
• 完全可控：生成的HTML字符串可自行缓存、保存或通过任意方式提供服务，不受框架限制。

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