如何在Node.js中使用自定义CSS样式化Swagger API文档？

问题根源 #

swagger-ui-express的customCss参数仅支持内联CSS字符串，直接传入文件路径（如../swagger.css）不会生效，因为它无法解析相对路径加载外部文件。

解决方案1：读取本地CSS文件内容传入 #

通过fs.readFileSync读取本地CSS文件的内容，将字符串赋值给customCss：

import * as fs from 'fs';
import * as path from 'path';
import swaggerUi from 'swagger-ui-express';
import yaml from 'js-yaml';
import express from 'express';

const app = express();

// 加载Swagger定义文件
const swaggerDefinition = yaml.load(
  path.join(__dirname, '..', 'swagger.yaml')
) as object;

// 读取自定义CSS文件内容
const customCssContent = fs.readFileSync(
  path.join(__dirname, '..', 'swagger.css'),
  'utf8'
);

const swaggerOptions = {
  customCss: customCssContent
};

// 挂载Swagger UI
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDefinition, swaggerOptions));

解决方案2：使用customCssUrl配合静态资源托管 #

将CSS文件作为静态资源托管，通过customCssUrl指定其访问路径：

1. 先托管静态资源目录（假设CSS文件放在项目根目录的public文件夹下）：

app.use(express.static('public'));

2. 设置Swagger UI选项：

const swaggerOptions = {
  customCssUrl: '/swagger.css' // 对应静态资源的访问路径
};

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDefinition, swaggerOptions));

解决方案3：内联CSS（确保选择器优先级） #

如果内联CSS未生效，检查选择器是否匹配Swagger UI的实际DOM结构，可通过浏览器开发者工具确认元素类名，同时提升优先级（比如添加!important或更精确的选择器）：

const swaggerOptions = {
  customCss: `
    /* 隐藏顶部导航栏 */
    .swagger-ui .topbar {
      display: none !important;
    }
    /* 修改标题颜色 */
    .swagger-ui .info .title {
      color: #2563eb;
    }
  `
};

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