Swagger: A Powerful Tool for API Development

Swagger is a tool that software developers use to simplify the implementation of RESTful web services. This framework allows for creating and documenting APIs with ease. As a result, Swagger promotes consistency and simplicity in API design, and accelerates API development by eliminating the need to hand-code complex API specifications. This article will discuss how to use Swagger in Visual Studio 2019.

What is Swagger?

Swagger is an open-source framework that greatly simplifies the process of designing, building, documenting, and consuming RESTful web services. Its straightforward approach defines the structures and data elements of an API with ease, allowing developers to easily discover and understand an API’s capabilities. As a result, it’s simpler to integrate with other software components and easier to consume.

How to Use Swagger in Visual Studio 2019

Step 1: Create a new ASP.NET Core Web Application

To start using Swagger in Visual Studio 2019, create a new ASP.NET Core Web Application project. Ensure that the target framework is set to .NET Core 3.1 or higher. Click the Web Application (Model-View-Controller) template, provide the project name, and click Create.

Step 2: Install the Required NuGet Packages

After creating a new project, navigate to the Solution Explorer, right-click on the project name and click Manage NuGet Packages. Search and install the following NuGet packages: Swashbuckle.AspNetCore and Swashbuckle.AspNetCore.SwaggerUI.

Step 3: Configure Swagger in the Startup Class

In Startup.cs file, configure Swagger by adding the following lines of code in the ConfigureServices method:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

In the Configure method add the following lines of code:

app.UseSwagger();
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1"));

The first line adds the Swagger middleware into the application pipeline, while the second line configures the Swagger UI to display API documentation.

Step 4: Define APIs Using Swagger Annotations

To define APIs using Swagger annotations, add the following lines of code to the top of the WeatherForecastController.cs file:

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.ComponentModel.DataAnnotations;
using Swashbuckle.AspNetCore.Annotations;

The method that you want to expose through API, add the following code:

[SwaggerOperation(
    Summary = "Gets the weather forecast for the next five days.",
    Description = "Returns a list of weather forecast objects.",
    OperationId = "GetWeatherForecast",
    Tags = new[] { "Weather" }
)]
[SwaggerResponse(200, "OK", typeof(IEnumerable<WeatherForecast>))]
[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();
}

The annotations added to the method provide details about its operations such as its summary, description, operation ID, and tags. Furthermore, it specifies the expected response code and data type.

Step 5: Build and Test the API with Swagger

After setting up Swagger in Visual Studio 2019, press F5 to build and run the application. Open the Swagger UI in your web browser by heading to https://localhost:5001/swagger/index.html.

To check your API’s details, click the GetWeatherForecast method under the Weather category. Then, the documentation appears, which shows the summary, description, operation ID, and response details that you specified. To test the API, click on the Try it out button and enter any required parameters. Click the Execute button to see the response.

Conclusion

By following the above steps, it is easy to incorporate Swagger into your Visual Studio 2019 projects and simplify API development. With Swagger, you can ensure that your APIs are consistent, well-documented, and easy to consume. This way, developers can focus on building high-quality applications rather than complex API specifications.