:::: MENU ::::

Adding swagger in ASP.NET Core Web API

In this post i will show how to add, configure and customize swagger in ASP.NET Core web API project.

Let’s start by creating new ASP.NET Core web API project and adding swagger in our project. For .NET there is open source project swashbuckle which provide swagger implementation. We need to get it from nuget.

In project.json file under dependencies node add required swagger package.

You need to add or configure swagger services in middleware in startup.cs file.

Now run your application and navigate to [localhost]/swagger/ui there you will get swagger page with all APIs beautifully documented.

This is the UI which you will get by default with least setup. Now lets start to customize its implementation and see other features too.

You can add your own description for your API.

You can enable swagger to use our XML comments. By default it does not use XML comments which we write for our actions, attributes etc. we need to configure it manually.

First, enable XML file documentation creation option from build option of project. Right click on project and go to properties option then on Build tab.

By enabling this option you will get xml file which includes all xml comments of your project. Created XML file will be saved in [content_root_path]\bin\[Debug/Release]\newcoreapp1.0 folder with the name [your assembly].xml. Now You know the location where xml file will be saved. Now let’s pass this file to swagger so that it can present your xml comment in beautiful documentation of your API.

Swashbuckle provides IncludeXMLComments method which takes path of XML file as a parameter which we created a moment ago (not created but saw how to create 🙂 ) and use it for the documentation of API. You can also see what are created in that XML file from bin folder.

-Comment Sample

-Customizing Including XML comments options

-XML comment converted into beautiful documentation.

Another basic settings that we need to customize is display status of enum values. By default swagger will document enum option as numeric values but we can customize it to show exact string values of enum by setting DescrcibeAllEnumsAsStrings method.

API without Configuring DescrcibeAllEnumsAsStrings option

API with Configuring DescrcibeAllEnumsAsStrings option

These are few of many options that you can customize in swashbuckle to create your swagger metadata. If you want to go through other options then jump to swashbuckle github.

That’s it. We have successfully added swagger in our ASP.NET Core web API project and also did customization for basic features.

Code is available in github.

Happy Coding 🙂

 


  • Chris Bertrand

    Minor issue with your code – given a default project as you detailed, IsDevelopment() does not exist under “Environment”. Not does “ContentRootPath”.

    • Chris Bertrand

      Found the entries in your source code (much thanks btw). Might just be worth including those tidbits here so that a full working example could be built from this article alone.