Customize Swagger to ASP.NET Core 2.1 Web API

salman lone
Jun 16, 2019 · 3 min read

If customize word is confusing you, you need to take a look our first article about adding swagger into ASP .Net Core 2.1 Web API.

In the current article, we will talk more about customization of swagger once you will install the basic swagger in ASP .Net Core 2.1 Web API.

XML comments

We are familiar with XML comments for documentation but swagger does not show XML comments by default. This option is available to show XML comments on swagger UI. We need to make sure that when we build our project, the comments are getting saved into an XML file. Swagger will use the XML file to show comments on swagger UI.

To make the XML file, right click on project in Visual Studio and then go to properties. Navigate to build tab and check “XML documentation file” option in output section.

In the value field for “XML documentation file” option, you need to specify complete path for your XML file like:

D:\CheckoutAd.Api\bin\Debug\netcoreapp2.1\CheckoutAd.Api.xml

The value in “Output path” should be like:

bin\Debug\netcoreapp2.1\

Now save the settings and Add a method in Startup.cs to get the path of generated XML. This code to get the XML path will work in your local environment as well as in the production environment.

Next, add code to include XML comments in ConfigureService method. Like:

Next, add XML comments to our actions. Here is XML comment for Delete method.

Now run the app, you should see XML comments.

Enum Values

You can display enum values in sawagger UI using DescribeAllEnumsAsStrings metod like:

The story does not stop here, you need to do a little more. Add an enum in the project like:

and then pass a parameter of the enum type into an endpoint like:

Now run the project again, you will see the enum values in your endpoint details like:

There is also a method named “DescribeStringEnumsInCamelCase” to convert enum string values in camel case.

Swagger Documentation For Each API Version

If you have multiple versions of your WEB API, then you can use swagger to generate the different document based on the selected version. Like:

Run the project again, you will see an option for version 2 in top right drop down in swagger UI like:

There is still more to cover for versioning of API but, for now try to understand and practice this first. Later will be discuss more about versioning of API in future articles.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade