Introduction to Swagger
Swagger is used to documenting the specification of Web APIs and test the Web APIs; this minimizes the time required to document the Web APIs.
The Swagger UI looks like this:
Demo:
a. Create a .Net Core Web API.
b. Install Swashbuckle.AspNetCore.Swagger NuGet package.
 |
services.AddSwaggerGen(
x =>
{
x.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Title = "Swagger Demo",
Version = "V1"
});
});
d. Next, in public void Configure(IApplicationBuilder app, IWebHostEnvironment env), add the below code.
app.UseSwagger();
app.UseSwaggerUI(c => {
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Test API V1");
});
e. Basic swagger documentation is ready now. Just launch the application with the swagger endpoint:https://localhost:44359/swagger
f. We can also add XML comments. This will help in documenting the API by adding more explanation to our APIs.
To add XML comments support for swagger, we need to first generate the XML comments file. To generate an XML comments file, we need to enable it in Visual Studio. To enable this, open the project's properties, then under Build, you will find Output->XML Documentation File. Select the checkbox.
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSwaggerGen(
x =>
{
x.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Title = "Swagger Demo",
Version = "V1"
});
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
x.IncludeXmlComments(xmlPath);
});
}
h. We can now add comments as below to the APIs and it will show in swagger as below:
/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
var rng = new Random();
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = rng.Next(-20, 55),
Summary = Summaries[rng.Next(Summaries.Length)]
})
.ToArray();
}
I. The swagger shows it as below:
These are just the basics of swagger. Swagger is powerful and provides us more features such as adding custom UI, adding authentication support for the Web API in the UI.
