Skip to content

Features

Jump to bottom
Teuz edited this page Nov 28, 2025 · 3 revisions

Discover everything SwaggerUI.Themes can do to transform your Swagger UI documentation. From beautiful themes to powerful UI enhancements and fine-grained customization—all designed to work together seamlessly.

Overview

SwaggerUI.Themes provides three main categories of features to enhance your API documentation:

Category What It Enables Quick Start
🎨 Theming Beautiful visual designs and custom branding Apply a predefined theme or create your own
⚡ UI Enhancements Interactive features for better navigation Enable advanced options with one line
🔧 Customization Fine-tune colors and icons Override CSS variables

Theming

Transform the look and feel of your Swagger UI with professionally designed themes or create your own custom designs.

Predefined Themes

Six ready-to-use themes that work out of the box:

Theme Description Best For Preview
Dark Dark theme with blue accents and high contrast Night-time development, reduced eye strain View →
Light Clean, bright theme with subtle colors Daytime use, presentations View →
Forest Nature-inspired green tones Environmental/eco-friendly APIs View →
DeepSea Deep ocean blue palette Data/analytics platforms View →
Desert Warm desert sand colors Creative/design APIs View →
Futuristic Vibrant neon colors with tech aesthetic Modern/cutting-edge projects View →

Quick Example:

app.UseSwaggerUI(Theme.Dark);

📖 Learn more about Predefined Themes →

Custom Themes

Create your own unique themes with four different approaches (from most to least powerful):

Method Best For Features
Theme Classes ⭐ Production custom themes Type-safe, auto-discovery
Embedded Files Custom branded themes CSS variables, organized code
Standalone Themes Unique, from-scratch designs Complete independence
Inline CSS Quick tweaks, prototyping Basic styling, rapid testing

📖 Learn more about Custom Themes →

UI Enhancements

Unlock powerful interactive features that improve navigation and user experience:

Feature Description Enable Method
Dynamic Theme Switcher 🔥 Allow users to switch between themes at runtime with auto-discovery EnableThemeSwitcher()
Sticky Operations Keeps operation summary visible while scrolling through long parameter lists EnableStickyOperations()
Pinnable Topbar Pin the navigation bar to stay visible while scrolling EnablePinnableTopbar()
Back to Top Quick scroll-to-top button for easy navigation ShowBackToTopButton()
Expand/Collapse All Bulk controls to expand or collapse all operations at once EnableExpandOrCollapseAllOperations()

Enable All Features

Enable all advanced features with a single method:

app.UseSwaggerUI(Theme.Dark, options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    options.EnableAllAdvancedOptions(); // Includes theme switcher
});

Enable Individually

Or enable specific features as needed:

app.UseSwaggerUI(Theme.Dark, options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

    // Enable only the features you want
    options.EnableThemeSwitcher();
    options.EnablePinnableTopbar();
    options.ShowBackToTopButton();
    options.EnableStickyOperations();
    options.EnableExpandOrCollapseAllOperations();
});

📖 Learn more about Advanced Options →

Customization

Fine-tune your theme's appearance using CSS variables for precise control over colors, icons, and more.

Quick Example

Override specific CSS variables to customize any theme:

:root {
  --topbar-background: #1a1a2e;
  --topbar-text-color: #eaeaea;
  --operation-get-background: #28a745;
  --operation-post-background: #007bff;
}

📖 View complete CSS Variables Reference →

Combining Features

All features work together seamlessly. Here are common combinations:

Example 1: Predefined Theme + All Features

app.UseSwaggerUI(Theme.Dark, options =>
{
    options.EnableAllAdvancedOptions();
});

Example 2: Custom Theme + Selective Features

app.UseSwaggerUI(CustomTheme.MyTheme, options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    options.EnablePinnableTopbar();
    options.ShowBackToTopButton();
});

Example 3: Full Customization

app.UseSwaggerUI(CustomTheme.Brand, options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    options.DocumentTitle = "My Company API Documentation";
    options.RoutePrefix = string.Empty;

    // All advanced features
    options.EnableAllAdvancedOptions();
});

Feature Compatibility

Understanding which features work together:

Feature Category Works With Predefined Themes Works With Custom Themes Works With Standalone Themes Works With CSS Variables
Dynamic Theme Switcher ✅ Yes ✅ Yes ❌ No³ ✅ Yes
Custom Themes (Inline/Embedded/Classes) ❌ No¹ ✅ Yes ❌ No¹ ✅ Yes
Predefined Themes N/A ❌ No¹ ❌ No¹ ✅ Yes
Standalone Themes ❌ No¹ ❌ No¹ N/A ⚠️ Manual²
UI Enhancements ✅ Yes ✅ Yes ❌ No³ ✅ Yes
CSS Variables ✅ Yes ✅ Yes ⚠️ Manual² N/A

Notes:

  1. Only one theme method can be active at a time. Choose either predefined, custom, or standalone.
  2. Standalone themes require manual integration of variables and features.
  3. UI enhancements and theme switcher require JavaScript, which standalone themes don't include by default.

Recommended Combinations

✅ Best Practices:

  • Predefined theme + UI enhancements + CSS variable overrides
  • Custom theme (Embedded/Classes) + UI enhancements + CSS variables + theme switcher
  • Inline CSS for quick prototyping, then migrate to Embedded Files for production

❌ Avoid:

  • Using InjectStylesheet() to override theme CSS (breaks theming system)
  • Standalone themes with UI enhancements or theme switcher (features won't work)

Next Steps

Choose your path based on what you want to accomplish:

I want to...

...apply a theme quickly

  1. Choose a predefined theme
  2. Follow the Getting Started guide
  3. Apply it: app.UseSwaggerUI(Theme.Dark);

...create a branded theme

  1. Review Custom Themes overview
  2. Choose the Embedded Files method or Theme Classes method
  3. Check the CSS Variables reference

...add interactive features

  1. Pick your theme (predefined or custom)
  2. Review Advanced Options
  3. Enable with options.EnableAllAdvancedOptions()

...fine-tune colors and spacing

  1. Start with a base theme
  2. Check CSS Variables reference
  3. Override specific variables in your CSS

...build something completely custom

  1. Review the Standalone Themes method
  2. Study the CSS Variables structure
  3. Build from scratch with complete freedom

Need Help?

Happy theming! 🎨

🏠 Home

🚀 Getting Started

✨ Features

📖 Migration Guides

Clone this wiki locally