Getting Started

Welcome to SwaggerUI.Themes! This guide will help you integrate beautiful themes into your Swagger UI documentation in seconds.

Installation

Choose your package based on your Swagger implementation:

Implementation	Package Name	NuGet Command
Swashbuckle	AspNetCore.SwaggerUI.Themes	dotnet add package AspNetCore.SwaggerUI.Themes
NSwag	NSwag.AspNetCore.Themes	dotnet add package NSwag.AspNetCore.Themes

Or use the NuGet Package Manager:

# Swashbuckle
Install-Package AspNetCore.SwaggerUI.Themes

# NSwag
Install-Package NSwag.AspNetCore.Themes

Swashbuckle.AspNetCore.SwaggerUI

Basic Setup

Add a theme to your existing Swagger UI configuration:

using AspNetCore.Swagger.Themes;

// In Program.cs
app.UseSwaggerUI(Theme.Dark);

With Options

You can still configure Swagger UI options as usual:

app.UseSwaggerUI(Theme.Dark, options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    options.RoutePrefix = string.Empty; // Serve at root
});

Enable Advanced Features

Unlock additional UI enhancements:

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

    // Enable all advanced features
    options.EnableAllAdvancedOptions();

    // Or enable individually:
    // options.EnablePinnableTopbar();
    // options.ShowBackToTopButton();
    // options.EnableStickyOperations();
    // options.EnableExpandOrCollapseAllOperations();
    // options.EnableThemeSwitcher();
});

See Advanced Options for details on all available features.

Browse Themes

Explore built-in themes ready to use. View all themes →

Note

Using InjectStylesheet() could have unintended effects. See Custom Themes for proper custom styling.

Example Project

Explore the Swashbuckle sample project for a complete working example.

NSwag.AspNetCore

Basic Setup

Add a theme to your existing Swagger UI configuration:

using AspNetCore.Swagger.Themes;

// In Program.cs
app.UseSwaggerUi(Theme.Dark);

With Settings

You can still configure NSwag settings as usual:

app.UseSwaggerUi(Theme.Dark, settings =>
{
    settings.Path = "/swagger";
    settings.DocumentPath = "/swagger/v1/swagger.json";
});

Enable Advanced Features

Unlock additional UI enhancements:

app.UseSwaggerUi(Theme.Dark, settings =>
{
    settings.Path = "/swagger";

    // Enable all advanced features
    settings.EnableAllAdvancedOptions();

    // Or enable individually:
    // settings.EnablePinnableTopbar();
    // settings.ShowBackToTopButton();
    // settings.EnableStickyOperations();
    // settings.EnableExpandOrCollapseAllOperations();
    // settings.EnableThemeSwitcher();
});

See Advanced Options for details on all available features.

Browse Themes

Explore built-in themes ready to use. View all themes →

Note

Setting CustomInlineStyles could have unintended effects. See Custom Themes for proper custom styling.

Example Project

Explore the NSwag sample project for a complete working example.

Troubleshooting

• Changes Not Appearing

Styles and JavaScript resources are cached by browsers.

If your theme changes aren't showing:

1. Clear browser cache and reload

2. Clear local storage:

   • Open browser DevTools (F12)
   • Go to Application/Storage tab
   • Clear Local Storage for your site

3. Restart your application to ensure resources are reloaded

• Theme Not Loading

Check your configuration:

// ✅ Correct
app.UseSwaggerUI(Theme.Dark, options => ...);

If using custom themes, ensure:

• CSS files are set as Embedded Resources
• Files are in the SwaggerThemes folder or in the same folder as the custom Theme class
• Namespace matches your project structure

• Advanced Features Not Working

Make sure you're enabling them:

// Features must be explicitly enabled
app.UseSwaggerUI(Theme.Dark, options =>
{
    options.EnableAllAdvancedOptions(); // All or individual features
});

Check browser console (F12) for JavaScript errors.

• Still Having Issues?

1. Check the Known Issues page for documented limitations
2. Check the GitHub issues for similar problems
3. Review the Migration Guide if upgrading
4. Open a new issue with:
   • Your package version
   • Framework version (.NET 6/7/8)
   • Minimal code example
   • Browser console errors (if any)

Next Steps

• Explore All Features - See everything SwaggerUI.Themes can do
• Explore Predefined Themes - See all available themes
• Create Custom Themes - Build your own theme
• Enable Advanced Options - Enhance your UI
• Use CSS Variables - Fine-tune theme colors

Quick Reference

Swashbuckle

using AspNetCore.Swagger.Themes;

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

NSwag

using AspNetCore.Swagger.Themes;

app.UseSwaggerUi(Theme.Dark, settings =>
{
    settings.Path = "/swagger";
    settings.EnableAllAdvancedOptions();
});