NestJS Swagger 自定义CSS样式配置指南

问题背景

在使用NestJS框架开发API接口时，Swagger UI是一个非常有用的API文档工具。开发者经常需要自定义Swagger UI的界面样式，使其更符合项目风格或企业品牌。然而，在实际配置过程中，可能会遇到自定义CSS文件无法加载的问题。

解决方案

基础配置方法

在NestJS中配置Swagger自定义CSS的基本方法是在Swagger模块的配置对象中添加customCssUrl属性，指向你的CSS文件路径：

SwaggerModule.setup('api', app, document, {
  customCssUrl: '/public/swagger-custom.css'
});

常见问题与解决

当按照上述方法配置后发现CSS没有生效时，通常是因为NestJS应用没有正确配置静态文件服务。Swagger UI虽然可以指定CSS文件路径，但实际文件需要通过静态资源服务提供。

静态资源服务配置

需要在main.ts中添加静态资源服务配置：

import { join } from 'path';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // 配置静态文件服务
  app.useStaticAssets(join(__dirname, '..', 'public'), {
    extensions: ['css', 'jpg', 'png'],
    index: false,
  });
  
  // Swagger配置
  const config = new DocumentBuilder()
    .setTitle('API文档')
    .setDescription('API描述')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document, {
    customCssUrl: '/swagger-custom.css'
  });

  await app.listen(3000);
}

关键点说明

1. 静态文件目录：确保CSS文件放置在项目的public目录下（或其他你指定的静态文件目录）
2. 路径配置：useStaticAssets中的路径配置要与实际文件存放位置一致
3. 文件扩展名：在extensions数组中包含'css'扩展名
4. URL路径：customCssUrl中的路径是相对于静态文件服务的根路径

进阶建议

1. CSS文件内容：可以参考Swagger UI的默认样式进行覆盖，使用浏览器开发者工具查看Swagger UI的元素类名
2. 缓存问题：开发过程中如果修改了CSS文件但没看到效果，可能是浏览器缓存导致的，可以尝试强制刷新或使用无痕窗口
3. 响应式设计：如果项目需要适配移动设备，可以在自定义CSS中添加媒体查询
4. 主题切换：可以通过CSS变量实现暗黑/明亮主题切换

总结

在NestJS项目中自定义Swagger UI样式需要同时配置Swagger模块和静态文件服务。理解这两者的关系是解决问题的关键。通过正确配置静态文件服务，开发者可以灵活地定制Swagger UI的外观，使其更好地融入项目整体风格。