Enabling Swagger In Your .NET Core 2.0 Application

Note

You can find the source code of my sample application here.

If you have ever worked with APIs, then you might be familiar with Swagger. If you have not heard about Swagger, then this post will help you to know the basics of Swagger and the steps to configure Swagger with your .NET Core 2.0 application.

First of all, let us see what Swagger is.

One liner for Swagger – UI representation of your RESTfull APIs.

Swagger is a set of rules (in other words, a specification) for a format describing REST APIs.
The format is both machine-readable and human-readable.
As a result, it can be used to share documentation among product managers, testers, and developers, but can also be used by various tools to automate API-related processes.

For example, if you have a set of APIs and you want a proper documentation for these APIs, you can use Swagger. You can even test the API calls from Swagger and there is lot more that can be done using Swagger Have a look here for more details.

In this post, we will see how can we use Swagger with .NET Core 2.0 application.

Step by step guide

Open Visual Studio 2017 and create a new project. Then, select Core Web application.

swa1

Click on OK. It will open the template window with different options of awesome templates to chose from. Select Web API.

swa2

It will create the API project with a structure shown below.

swa3

Let us add Swagger to the middleware. Open Startup.cs class and add the below code to the ConfigureService method.

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services) {
services.AddMvc();
services.AddSwaggerGen(c => {
c.SwaggerDoc("v1", new Info {
Version = "v1",
Title = "My First API",
Description = "My First ASP.NET Core 2.0 Web API",
TermsOfService = "None",
Contact = new Contact() {
Name = "Neel Bhatt", Email = "[email protected]", Url = "https://neelbhatt40.wordpress.com/"
}
});
});
}

Once you add the above code, an error will be shown because IServiceCollection does not contain the definition for AddSwaggerGen.

swa4

We will have to add a NuGet package – Swashbuckle.AspNetCore to add this support which is used to add the Swagger tools for documenting APIs built on ASP.NET Core.

Search Swashbuckle.AspNetCore in NuGet Package manager and select the package as shown below.

swa5

Once you install the Nuget package, errors will be gone.

Once this is done, we will enable THE Swagger UI. Add THE below code in Configure method of Startup.cs class.

public void Configure(IApplicationBuilder app, IHostingEnvironment env) {
if (env.IsDevelopment()) {
app.UseDeveloperExceptionPage();
}
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(c => {
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
}

We are almost done and we have already enabled Swagger in the Core 2.0 application.

The last but not least step, we will change the Launch Browser settings of the application and will tell the application to launch Swagger when we run the application.

For this, open Properties of the application, go to Debug tab, and write Swagger in the "Launch browser" text box,

swa6

That is it. Just run the application and you will see beautiful colorful Swagger landing page as shown below,

swa7
Manage versions of APIs

You can even manage different versions of your APIs, for example, you have v2 APIs as well and you need to enable that in Swagger then you just need to add a couple of steps.

First, add new SwaggerDoc in ConfigureService method and then add new endpoint in Configure method in Startup.cs class as shown below,

swa8

Now just run the application and you can select different versions of your APIs by selecting the value from dropdown list as shown below,

swa9
XML documentation

We all are quite familiar with the XML document of the API, for example, you have hosted your APIs and you want to send the details of APIs to another team then you can simply pass XML document which contains all the details of the API like description, desired input, output etc.

Let us see how we can create XML documents with Swagger in .Net Core 2.0 application,

First of all, we need to enable XML support and once we enable the checkbox, the application will create an XML file in the bin\debug folder.

Open properties – > Open Build tab -> Enable check box XML documentation file as below,

swa10

Once this is done, we need to add below lines of code in the ConfigureService method which will include the comments into the XML file,

var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "NeelSwaggerSampleApplication.xml");
c.IncludeXmlComments(xmlPath);

Now add some comments on any random method as shown below,

swa11

And when you build the solution, XML file would be generated in bin\debug folder. Open the XML file, it will show these comments,

swa12
Have a look at the Github page of Swagger UI if you want more information.

You can find the source code of my sample application here.

Hope it helps.

2 Comments

Join the conversation! Your thoughts help the community grow.

Riste Golaboski7y ago
Amazing and very thorough guide mate, keep up the good work.
Martin Nkala8y ago
How to make the the different versions to show on seperate swagger.json files. i.e swaggerV1.json for version 1 and swaggerV2.json for version 2. right now both changes of v1 and v2 go to swagger.json.