“Swagger is a simple yet powerful representation of your RESTful API. According to Swagger.io, it is basically an open-source software framework with a large ecosystem of tooling that helps developers design, build, document, and consume RESTful web services.
We are going to cover how to add swagger to ASP.NET Core 3.0 Web API. Swagger is an api testing tool and it is very easy to use swagger with ASP.NET Core 3.0 Web API. We can test our APIs using swagger. Swagger is an Unordered List of representation of RESTful API.
How to create web api using asp.net core 3.0
We will create a new ASP.NET Core 3.0 Web API using Visual Studio 2019 preview. So, open visual studio, then click on “Create a new project”, and then select “ASP.NET Core Web Application” and then click on “Next” button. Then enter the name of API, and then location of your project and then click on “Create” project. Then select asp.net core version from upper dropdown and then click on “API” template and then finally click on “OK” button.
Add packages for swagger
After creating the asp.net core 3.0 web API, now add packages for swagger in asp.net core 3.0 web api project. So, open nuget packages and install NuGet packages as you see in the below screenshot.
Add swagger to ASP.NET Core 3.0 Web API
In this step, we will add swagger to ASP.NET Core 3.0 Web API. So, go to project folder structure and then open startup.cs and then add the middleware as you see in the below file code
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen(c =>
{
c.SwaggerDoc(“v1”, new Info
{
Version = “v1”,
Title = “API”,
Description = “Test API with ASP.NET Core 3.0”,
TermsOfService = “None”,
Contact = new Contact()
{
Name = “Dotnet Detail”,
Email = “dotnetdetail@gmail.com”,
Url = “www.dotnetdetail.net”
},
License = new License
{
Name = “ABC”,
Url = “www.dotnetdetail.net”
},
});
});
}
Now, enable the swagger UI in Configure() method.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint(“/swagger/v1/swagger.json”, “Test API V1”);
});
}
Now, change the default load URL. So, go to project folder structure and then right click on project => then select properties => and then go to “Debug” tab and then change the launch browser value as you see in the below screenshot.
This is all that you need to add swagger to asp.net core 3.0 web api. So, now run the project and you will see the output as you see in the below output screenshot.
How to show XML comments in swagger ui url
In this section, we will add XML comments. By default, swagger doesn’t show XML comments. Let’s see how to add XML comments with swagger ui url.
So, go to project folder structure and then right click on the project and then select properties and then navigate to the build tab. And now check the “XML documentation file”’ as you see in the below screenshot. Using this option, XML comments are saved in an XML file with the name of your_assembly.xml.
Now, we need to add Swashbuckle’s IncludeXmlCommetns() method in startup.cs class. So, write this below code within the AddSwaggerGen middleware.
var xmlFile = $”{Assembly.GetExecutingAssembly().GetName().Name}.xml”;
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
Now, add XML comments just above our method as you see in the below code.
// GET api/values
/// <summary>
/// Get API Value
/// </summary>
/// <remarks>This API will get the values.</remarks>
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { “value1”, “value2” };
}
Now, just run the project and you will see the output as you see in the below screenshot.
How to add different swagger documents for different versions of API
In this section, we will see how to add different swagger documents for different versions of API. This will help us, if we have multiple versions of web API. So, add this below code within the AddSwaggerGen middleware in startup.cs class.
c.SwaggerDoc(“v2”, new Info
{
Version = “v2”,
Title = “Test API”,
Description = “Test API 2 with ASP.NET Core 3.0”,
TermsOfService = “None”,
Contact = new Contact()
{
Name = “Dotnet Detail”,
Email = “dotnetdetail@gmail.com”,
Url = “www.dotnetdetail.net”
},
License = new License
{
Name = “ABC2”,
Url = “www.dotnetdetail.net”
},
});
Now, add this below code within the Configure method.
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint(“/swagger/v2/swagger.json”, “Test API V2”);
});
Swagger makes it easy to automatically provide fairly complete information about an API endpoint. Having this information present and available helps make everyone’s life better. Thanks for the read, if you have any questions feel free to comment of contact us via email: sales@arnasoftech.com