How I Customized The Swagger UI In ASP.NET Core
Tags: api, dotnet, sideprojects, tips
Published: 2020-05-11 11:43:38

Photo by Ern Gan on Unsplash

*Originally published on my blog at [halldorstefans.com](https://www.halldorstefans.com/how-i-customized-the-swagger-ui-in-asp-net-core/) on May 11, 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.

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

Below are the changes I made in order 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 few simple changes in the `Startup` file:

```dotnet
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 both in the favicon and in the topbar, on the top left corner of the site.

### 1. Favicon

To change the favicon, the first step is to make sure you have your favicon. [RealFaviconGenerator](https://realfavicongenerator.net/favicon/aspnet_core) is a great favicon generator if you need one.

Once you have your favicon, you need the create the directory `wwwroot/docs` where the `docs` part is from the [Route Change](#route-change) above. So if you haven't changed your route, the directory would be `wwwroot/swagger`.

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

![Custom CSS folder](https://hsblogimages.blob.core.windows.net/ghost/swaggerCSS.png)

Also make sure that the application uses static files configuration:

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

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

### 2. Topbar Logo

Replacing the logo in the topbar means we need to do a little bit of CSS magic.

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

In that CSS file I added the following:

```css
.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 replaced the logo with a text, but you should be able to replace it with your own logo.

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

```dotnet
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 I replaced it with a red colour.

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

```css
    .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.

```dotnet
public void Configure(...)
{
    ...

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

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

---

You can see my outcome [here](https://mclarenapi.azurewebsites.net/docs/index.html) and the source code [here](https://github.com/halldorstefans/McLarenAPI).

Hopefully this helped.
Have a great day.

---

Thank you for reading. For weekly updates from me, you can sign up to my [newsletter.](https://email.halldorstefans.com/)