Customizing Swagger in ASP.NET Core 5

Many of us use Swagger and Swashbuckle to document our APIs in C #. They are very easy to use, to the point that they are already included in the webapi base template project. Thanks to this, we can reduce the time we spend documenting a service. But sometimes the default configuration is not enough. In this article, I will give some tips and examples of how to customize swagger to our liking.

Include comments

The best way to enrich the documentation in Swagger is by using the comments in your source code. First, set the GenerateDocumentationFile option to true in your project solution.

Enable generate documentation file

And then configure Swager to include XML comments.

Include XML comments

The rest is up to you. You should write a complete documentation of all your endpoints. I’ll show you an example of what you should include in the comments.

Comments example

The result will be something like this:

Fill Open API info

Fill in the metadata for you Open API

• Title
• Description: A short description of the service.
• Version: The version of the Open API document. Is required.
• Terms of Service: A URL to the Terms of Service for the API. Must be in the format of a URL.
• Contact: The contact information for the exposed API.
• License: The license information for the exposed API.

Convert URLs to lowercase

By default, the routes appear with the initial in capital letters, for me this is less readable. For example, api/Teams instead of api/teams. To solve this issue, we can write a simple filter.

PathLowercaseDocumentFilter.cs

And then register the filter:

Registering the filter

Change the documentation path

By default, the Swagger documentation serve in the path /swagger. We only have to change the RoutePrefix and RouteTemplate properties to achieve this.

Changing route to /docs/api

Style Swagger 💅

We can overwrite the styles that come by default, injecting our own CSS file. Take into consideration that we must have app.UseStaticFiles() enabled. And then create a CSS file in the wwwroot folder.

Add custom CSS

You can find a wide variety of Swagger themes online, starting here:

GitHub - ostranme/swagger-ui-themes: A collection of CSS themes to spice up your Swagger docs

Add a static sidebar

Give your API a more personalized touch by including a static navigation bar. Add an HTML file in wwwroot with the source code of your custom bar.

wwwroot/custom-sidebar.html

Add styles to wwwroot/swagger-custom.css

Include your navigation bar in the UI configuration by setting up HeadContent.

Static custom sidebar

Add custom JS

Adding JavaScript is very easy. All you have to do is create a JS file in the wwwroot folder and then include it as part of the SwaggerUI configuration.

You can also include external libraries like jQuery.

And that’s it

With these simple steps, you can customize Swagger to your liking and give it a better look. I hope this article on how to customize ASP.NET Core 5 has been helpful. Thank you very much for reading it.

Protect Your Online Privacy with NordVPN

Disclosure: This section contains promotional content.

NordVPN is a Virtual Private Network (VPN) service that provides users with a secure and private way to access the internet.

In the modern digital landscape, ensuring online security and privacy has become of utmost importance. With the surge in cyber threats and data breaches, safeguarding your sensitive information is now an essential task. This is where NordVPN steps in — a robust solution that offers a secure and confidential online browsing encounter. Take control of your online presence

🔒 NordVPN: Get up to 65% discount with our NordVPN promotion code

🔒 NordLocker: Get up to 53% discount with our NordLocker promotion code

🔒 NordPass: Get up to 50% discount with our NordPass promotion code

Please note that discounts may vary over time.