How To Customize Swagger UI in ASP.NET Core

10 May, 2020

Many of us use Swagger and Swashbuckle on ASP.NET Core to have some minimal documentation for our API.
It's really easy to integrate with your API and gives a good overview of the available endpoints in the API.

However, you might find that the Swagger UI doesn't fit your colour scheme and/or you want to replace the Swagger branding with your own. Thankfully, the steps to change that are rather simple.

Below are my changes to make the UI more fitting for my API.

Route Update

The default Swagger UI page is under myapp.com/swagger/index.html. But you can change the /swagger/ part.
I, for example, changed my route to /docs/.
This can be done with a few simple changes in the Startup file:

public void Configure(...)
{
    ...
    app.UseSwagger(options =>
    {
        options.RouteTemplate = "docs/{documentName}/docs.json";
    });

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

        options.RoutePrefix = "docs";
    });
}

Replace Swagger Icon/Logo

The Swagger logo can be seen in the favicon and in the top bar, which is located at the top left corner of the site.

1. Favicon

The first step in changing the favicon is to make sure you have one. RealFaviconGenerator is a great favicon generator.

Once you have your favicon, you need to create the directory wwwroot/docs, where the docs part is from the Route Change above. So, if you haven't changed your route, the directory will be wwwroot/swagger.

You then copy-paste your favicon into that folder. Ensure the files favicon.ico, favicon-16x16.png, and favicon-32x32.png are included.
So, you should see something like this:

swaggerCSS

Also, make sure that the application uses the static files configuration:

public void Configure(...)
{
    ...
    app.UseStaticFiles();
    ...
}

You might need to press Ctrl + F5 for a cache refresh to make the favicon change appear.

Replacing the logo on the top bar means doing some CSS magic.

A custom CSS file is needed under wwwroot/swagger-ui/custom.css.

In that CSS file, I added the following:

.topbar-wrapper img[alt="Swagger UI"], .topbar-wrapper span {
    visibility: hidden;
}

.topbar-wrapper .link:after {
    content: 'Unoffical McLaren F1 API';
    color: #fff;
    visibility: visible;
    display: block;
    position: absolute;
    padding: 15px;
}

This replaces the logo with text, but you should be able to replace it with your logo.

Once that is ready, the following code must be added to include the custom CSS changes.

public void Configure(...)
{
    ...
    app.UseStaticFiles();
    ...
    app.UseSwaggerUI(options =>
    {
        ...
        options.InjectStylesheet("/swagger-ui/custom.css");
        ...
    });
}

Change The Green Colour

This part builds on the last one. I wanted to replace the default Swagger green colour with something else, in my case, a red colour.

So, here, I added to the custom CSS file created earlier.

.swagger-ui .topbar .download-url-wrapper .select-label select {
    border-color: #EF1C25;
}

.swagger-ui .info .title small:last-child {
    background-color: #EF1C25 !important;
}

What Else?

It's also possible to inject a custom JavaScript in the same way as the CSS.

public void Configure(...)
{
    ...

    app.UseSwaggerUI(options =>
    {
        ...
        options.InjectJavascript("/swagger-ui/custom.js");
        ...
    });
}

So, with the custom CSS and JavaScript, you can customize the UI to your liking.

You can see the source code here.

Hopefully, this helped. Have a great day.

Thank you for reading.

Halldor Stefansson