SwaggerUI.Themes

Change style to your API documentation in ASP.NET Core applications!

Package	Purpose
	Customize the style for Swashbuckle.AspNetCore.SwaggerUI
	Customize the style for NSwag.AspNetCore

[!WARNING] Starting from v1.0.0 the namespace for pre-defined styles is AspNetCore.Swagger.Themes instead of AspNetCore.SwaggerUI.Themes!

Features

New Themes: enhances the Swagger documentation interface with various themes, including a default style that preserves the classic Swagger UI appearance and introduces new modern styles. Explore samples here.
Seamless Integration: simply install the package and add the style parameter to the existing method used for Swagger UI.
🆕 Custom Styles: create your own style for Swagger documentation. You can either inherit from the classic or modern common styles, or define a completely new style (see more here).

Supported .NET Versions

Version	Status
.NET 6
.NET 7
.NET 8

Swashbuckle.AspNetCore.SwaggerUI

Customize the Swashbuckle API documentation UI by using AspNetCore.SwaggerUI.Themes in your ASP.NET Core project:

Install the package using .NET CLI or NuGet Package Manager:

dotnet add package AspNetCore.SwaggerUI.Themes

Install-Package AspNetCore.SwaggerUI.Themes

In your Program.cs file, add the style through the Style, ModernStyle or NoJsModernStyle class as new parameter of app.UseSwaggerUI() method:
```
using AspNetCore.Swagger.Themes;

...

app.UseSwaggerUI(ModernStyle.Dark, options => ...);
```
This code enables the chosen theme for Swagger UI in your application.

[!NOTE] Using the InjectStylesheet() method in the Swagger UI configuration will override the provided style. See here how to inject custom styles.

NSwag.AspNetCore

Customize the NSwag API documentation UI by using NSwag.AspNetCore.Themes in your ASP.NET Core project:

Install the package using .NET CLI or NuGet Package Manager:

dotnet add package NSwag.AspNetCore.Themes

Install-Package NSwag.AspNetCore.Themes

In your Program.cs file, add the style through the Style, ModernStyle or NoJsModernStyle class as new parameter of app.UseSwaggerUi() method:
```
using AspNetCore.Swagger.Themes;

...

app.UseSwaggerUi(ModernStyle.Dark, settings => ...);
```
This code enables the chosen theme for Swagger UI in your application.

[!NOTE] Setting the CustomInlineStyles property while configuring the NSwag settings will override the provided style. See here how to inject custom styles.

Available Themes

There are a few pre-defined styles available for your Swagger UI.

Classics:

Dark	Forest	DeepSea	Desert

`Style.Dark`	`Style.Forest`	`Style.DeepSea`	`Style.Desert`

The light style is not in this list because it's just the default one used by Swagger UI; to use that you don't need this library.

Moderns:

Light	Dark	Forest

`ModernStyle.Light`	`ModernStyle.Dark`	`ModernStyle.Forest`

DeepSea	Desert	Futuristic

`ModernStyle.DeepSea`	`ModernStyle.Desert`	`ModernStyle.Futuristic`

[!TIP] Opt for Modern Styles! Modern styles come with additional functionalities, including pinned topbar and back-to-top button.

🆕You can also choose for a version without additional JavaScript if desired by using the pre-built NoJsModernStyle class.

[!NOTE] The classic and modern dark styles will only load if your browser's color scheme preference is set to dark; otherwise, the light style is loaded.

🆕Custom Styles

You can customize the Swagger UI in your ASP.NET Core application by applying custom CSS styles. Here are the available methods.

Inline CSS Styles

You can directly write your custom CSS content as a string and apply it to the Swagger UI:

var cssContent = "body { background-color: #f5f5f5; }";

// Swashbuckle
app.UseSwaggerUI(cssContent, options => ...);

// NSwag
app.UseSwaggerUi(cssContent, settings => ...);

Applying Embedded CSS Files from Assemblies

To apply a CSS file that is embedded as a resource within an assembly, place the file in a folder named "SwaggerThemes" inside the assembly. Then, specify the CSS filename and the assembly where the file is located:

var assembly = Assembly.GetExecutingAssembly();
var cssFileName = "myCustomStyle.css"; // Only the filename, no need to specify the "SwaggerThemes" folder

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

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

[!TIP] If your CSS file's name starts with "classic." or "modern.", the method automatically prepends a related common style (either classic or modern) to your custom styles. These common styles serve as the base for pre-defined styles that enhance the Swagger UI.

Creating Custom Styles by Inheriting from Base Classes

Another powerful customization option is to create your own style classes by inheriting from the Style, ModernStyle or NoJsModernStyle base classes. This approach allows you to define new styles that automatically incorporate common base styles and, for modern themes, additional JavaScript.

Here’s how to create a custom style:

// Use modern style loading additional JS
public class CustomModernStyle : ModernStyle
{
    protected CustomModernStyle(string fileName) : base(fileName)
    {
    }

    public static CustomModernStyle CustomModern => new("modern.custom.css");
}

// Use modern style without loading additional JS
public class CustomNoJsModernStyle : NoJsModernStyle
{
    protected CustomNoJsModernStyle(string fileName) : base(fileName)
    {
    }

    public static CustomNoJsModernStyle CustomModern => new("modern.custom.css");
}

// Use classic style
public class CustomStyle : Style
{
    protected CustomStyle(string fileName) : base(fileName)
    {
    }

    public static CustomStyle Custom => new("custom.css");
}

Place your CSS file (e.g., "custom.css") as an embedded resource in the same assembly where your custom style class is located. Then, apply it to the Swagger UI:

var customStyle = CustomStyle.Custom;

// Swashbuckle
app.UseSwaggerUI(customStyle, options => ...);

// NSwag
app.UseSwaggerUi(customStyle, settings => ...);

[!NOTE] Custom styles that inherit from the ModernStyle class include additional JavaScript. This doesn't apply to styles that inherit from NoJsModernStyle, inline styles, or those applied directly from assemblies.

Contributing

If you have any suggestions, bug reports, or contributions, feel free to open an issue or submit a pull request

teociaps / SwaggerUI.Themes

readme