Swagger in ASP.NET Core: Tips & Tricks

This post contains a few tips and tricks that can help you transform your swagger UI into an interactive documentation. If you don’t yet know how to install swagger in ASP.NET Core, this post will help you Get started with Swagger and ASP.NET Core.

How to change the URL of the Swagger UI

By default, the Swagger UI can be found at http://localhost:/swagger. To change the path and set, for example, the Swagger UI at the app’s root, use:

How to revert Swagger JSON to version 2.0

By default, Swashbuckle generates and exposes Swagger JSON in version 3.0 of the specification -officially called the OpenAPI Specification. To support backwards compatibility, you can opt into exposing JSON in the 2.0 format instead:

How to add author, license, and description

If you want, you can pass information such as the author, license, and description, using the OpenApiInfo object:

How to include XML commenting

One of my favorites and very useful features, is to enable swagger to read the XML comments of your actions and objects, transforming it to an interactive documentation.

To do this, you first need to enable the creation of the XML documentation file:
Visual Studio, Enable XML Documentation

  1. Right click on the project you wish to enable XML Documentation
  2. Click on “Properties
  3. Go to “Build
  4. Check the “XML Documentation File:” checkbox
  5. Change the path and point to the root of your app (use no path at all)
  6. Suppress the 1591 compiler warning to avoid headaches

Enabling XML comments provides debug information for all undocumented public types and members. Undocumented types and members are indicated by the warning message. That is why, step 6 is a very good idea!

You need to enable XML commenting for every solution configuration (e.g. Debug and Release)

Once done, just instruct Swagger generator to include the comments:

How to enrich your Swagger UI by annotating your models

Mark the model with attributes, found in the System.ComponentModel.DataAnnotations namespace, to help drive the Swagger UI components. For example, the following sample model is of an address, annotated with MinLengthAttribe and MaxLengthAttribute

The result of which, is the following in Swagger UI:
Swagger - Sample with an address

How to describe “Response types”

Return behavior and status codes is one of the most important concerns a developer has while consuming a RESTful API. Without proper description of the possible outcomes of an action, the consumer is left with unexpected behaviors, something that will not make you popular – at least not for good reasons.

In the following example, taken from Microsoft, we can see how to describe “Response Types“:

How to brand or theme Swagger UI

The default UI is great but there are cases where you need to your API documentation pages to represent your brand or theme. Branding the Swashbuckle components requires adding the resources to serve static files and building the folder structure to host those files.

In order to do that, you first need to enable static files middleware:

And then, after creating your own CSS, feed it to swagger:

The end!

Any more configurations you think I should include? Drop me a line, there are sure numerous other tips and tricks!

For a Quick Start guide on how to install Swagger visit Get started with Swagger and ASP.NET Core.