Method Embedded Files

Embedded CSS Files

Embed CSS files as resources in your project for powerful, organized customization.

Overview

Embedded CSS files offer a good balance between simplicity and power. They support CSS variables, advanced features, and inherit from base themes while keeping your styles organized.

Tip

For the most powerful approach with type-safety and auto-discovery, consider Theme Classes instead.

Setup

1. Create a folder named SwaggerThemes in your project (this name is required)
2. Add your CSS file to this folder (e.g., my-custom-theme.css)
3. Set Build Action to Embedded Resource:
   • Right-click the file → Properties
   • Set "Build Action" to "Embedded resource"

Note

The SwaggerThemes folder name is required for Embedded Files. If you want more flexibility over folder naming and location, consider using Theme Classes instead.

Usage

var assembly = Assembly.GetExecutingAssembly();
var cssFileName = "my-custom-theme.css";

// Swashbuckle
app.UseSwaggerUI(assembly, cssFileName, options => { });

// NSwag
app.UseSwaggerUi(assembly, cssFileName, settings => { });

Example CSS File

/* my-custom-theme.css */
/* Inherits base theme variables and styles */

:root {
  /* Override theme colors */
  --swagger-main-color: #ff6b35;
  --body-background-color: #f5f5f5;
  --topbar-background-color: #2c3e50;

  /* Customize buttons */
  --button-execute-background-color: #27ae60;
  --button-execute-border-color: #229954;
}

/* Additional custom styles */
.swagger-ui .topbar {
  border-bottom: 3px solid var(--swagger-main-color);
}

Benefits

✅ Inherits base theme - Gets all default styles and variables
✅ Advanced features available - Can use pinnable topbar, sticky operations, etc.
✅ CSS variables support - Full CSS Variables available
✅ Maintainable - Organized as project resources
✅ Minification support - Use .min.css files for production
✅ Reusable - Share across projects

File Structure

Simple structure:

YourProject/
├── SwaggerThemes/
│   ├── corporate.css
│   ├── minimal.css
│   └── dark-mode.css
└── Program.cs

Tip

For advanced organization including nested folders and standalone variants, see Custom Themes - Organizing Your Themes.

Build Configuration

Ensure CSS files are embedded in your project file:

<!-- YourProject.csproj -->
<ItemGroup>
  <EmbeddedResource Include="SwaggerThemes\your-theme.css" />
</ItemGroup>

Combining with Advanced Options

var assembly = Assembly.GetExecutingAssembly();

app.UseSwaggerUI(assembly, "my-theme.css", options =>
{
    // Enable all advanced features
    options.EnableStickyOperations();
    options.EnablePinnableTopbar();
    options.EnableBackToTop();
    options.EnableExpandCollapseAll();
    options.EnableThemeSwitcher();
});

Theme Switcher Support

Embedded CSS files work with the Dynamic Theme Switcher, but themes must be explicitly selected using the assembly overload:

var assembly = Assembly.GetExecutingAssembly();

app.UseSwaggerUI(assembly, "corporate.css", options =>
{
    options.EnableThemeSwitcher(); // ✅ Works with assembly selection
});

Note

Embedded files are not auto-discovered by the theme switcher. Only the explicitly selected theme and other class-based themes will be available. For auto-discovery of embedded custom themes, use Theme Classes instead.

Naming Convention: File names are converted to display names:

• corporate-blue.css → "Corporate Blue"
• dark-mode.css → "Dark Mode"
• myCustomTheme.css → "My Custom Theme"

Learn more about theme switcher configuration.

Minification

You can use minified CSS files for better performance. The library does not automatically minify your CSS - you need to create minified versions yourself.

File naming:

SwaggerThemes/
├── corporate.css          ← Development version
├── corporate.min.css      ← Minified for production
└── minimal.css

Usage:

var assembly = Assembly.GetExecutingAssembly();

// Use minified version in production
var cssFile = builder.Environment.IsDevelopment()
    ? "corporate.css"
    : "corporate.min.css";

app.UseSwaggerUI(assembly, cssFile, options => { });

Creating minified files:

Use tools like:

• csso-cli: csso corporate.css -o corporate.min.css
• PostCSS + cssnano: postcss corporate.css -o corporate.min.css --use cssnano
• Online tools: CSS Minifier

Tip

For easier minification control with a useMinified flag, consider using Theme Classes.

Best Practices

Use CSS Variables

Leverage predefined variables for consistency:

:root {
  /* Good - uses variables */
  --swagger-main-color: #your-brand-color;
}

/* Avoid - hardcoded colors everywhere */
.some-class {
  color: #your-brand-color;
}

Organize Your Variables

Group related variables together:

:root {
  /* Brand Identity */
  --swagger-main-color: #003d82;

  /* Layout */
  --body-background-color: #ffffff;
  --topbar-background-color: #f8f9fa;

  /* Operations */
  --opblock-get-background-color: #e3f2fd;
  --opblock-post-background-color: #e8f5e9;

  /* Buttons */
  --button-execute-background-color: #27ae60;
}

Next Steps

• Use Theme Classes - Type-safe approach with auto-discovery
• View all CSS Variables - Complete customization reference
• Enable Advanced Options - Add interactive features
• Enable Theme Switcher - Let users choose themes at runtime
• Create Standalone Themes - Full control and portability

---

← Custom Themes Overview