Using Swagger/OpenAPI with an ASP.NET Core API Project

Introduction 

I recently had a new task where I had to add Swagger/OpenAPI to an ASP.NET Core API project. This was my first-time integrating Swagger/OpenAPI in an ASP.NET Core project so I planned to create a simple test project to see how everything fitted together. My first point-of-call was to consult the Microsoft documentation on this, and while it is covered, I wanted a complete start-to-finish project showing all the steps required. I then proceeded to do some searching of my own but could not find anything that served my needs. Hence, I realised that I would have to figure it out myself. I also thought it would make for a good article that others can reference.

What is Swagger/OpenAPI? 

Taken directly from the Microsoft Documentation: 

Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Its main goals are to: 

  • Minimize the amount of work needed to connect decoupled services. 
  • Reduce the amount of time needed to accurately document a service. 
  • The two main OpenAPI implementations for .NET are Swashbuckle and NSwag 

The Swagger project was donated to the OpenAPI Initiative in 2015 and has since been referred to as OpenAPI. Both names are used interchangeably. However, “OpenAPI” refers to the specification. “Swagger” refers to the family of open-source and commercial products from SmartBear that work with the OpenAPI Specification. Subsequent open-source products, such as OpenAPIGenerator, also fall under the Swagger family name, despite not being released by SmartBear. 

In short: 

  • OpenAPI is a specification. 
  • Swagger is tooling that uses the OpenAPI specification. For example, OpenAPIGenerator and SwaggerUI. 

That explains it quite nicely. We will be using the Swagger tooling to contruct a SwaggerUI for the application that conforms to the OpenAPI specification. 

The documentation states that either Swashbuckle or NSwag can be used. From experimentation I found that Swashbuckle is easier to use when generating a SwaggerUI as part of the build process which “just works” as part of your application. NSwag seems better suited when you want to integrate with external third-party APIs or make use of tools like NSwagStudio. For this application, I decided to go with Swashbuckle. 

Setting up the project 

I will be using Visual Studio 2019 for this project, but it can be done with Visual Studio Code and Visual Studio for Mac as well. The first step is to create a new project. I used the ASP.NET Core Web API project template. This can also be accomplished via the command line with dotnet new webapi or selecting Web and Console > App > API > Next in Visual Studio for Mac. 

Next, give the project a name (I called mine Learning Swagger) and choose where to save it. For Target Framework I selected .NET 5.0 (Current). I deselected Enable OpenAPI support because I want to go through the steps manually to add this to a project. 

Graphical user interface, application, Teams

Description automatically generated

Once the solution was created, I ran the project to confirm everything was set up correctly. This resulted in a bunch of JSON from the template being output into the browser when accessing the /weatherforecast URL. 

Graphical user interface, text, application

Description automatically generated

Time to stop the running project and integrate Swagger! 

Integrating with Swagger 

The first step to take is installing the Swashbuckle NuGet package. This can do be accomplished by right-clicking on the project and selecting Manage NuGet Packages… 

A picture containing text, monitor, computer, indoor

Description automatically generated

In the window that appears, select Browse and search for Swashbuckle.AspNetCore. You will see all the options appear in the list below. Select Swashbuckle.AspNetCore. If you want to follow along with this guide, use the same version to avoid breaking changes that may occur in newer versions. The version being installed here is stable 6.1.4. Click Install and accept the licence agreement when prompted. 

Text

Description automatically generated

Once the Nuget package has been successfully installed, the next step is to configure the Swagger middleware. This is accomplished in the Startup.cs file. 

Inside the Startup class, within the ConfigureServices method, you’ll find a call to services.AddControllers(); Add the following code below that line: 

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

The first string indicates the name of the Swagger document. I called it “LearningSwaggerApiDoc”, but in a real-world application you would likely choose something like “v1” to indicate that this is the document for version 1 of your API. You could then add other docs such as “v2” for later revisions of the API.

The Title inside OpenApiInfo will be used on the documentation page for as title. 

The Version inside OpenApiInfo tells Swashbuckle which version of the OpenAPI specification to use. In this example, we are using version 1 (“v1”). 

We’ve now configured the application to generate the OpenAPI compliant files, but still need to use Swagger to generate a pretty UI on top of it. To do that, we need to add the following lines to the Configure method:  

app.UseSwagger(); 
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/LearningSwaggerApiDoc/swagger.json", "Learning Swagger API Doc Name")); 

You might want to add this inside the env.IsDevelopment() section if you do not want to expose your API documentation on the production application. 

The important parts of the above code are the LearningSwagegrApiDoc piece which needs to be the same as the name property of the c.SwaggerDoc method. This is because the .UseSwaggerUI() method tells Swashbuckle where to find the .json that is generated by the c.SwaggerDoc() method. The name here is the name used in the dropdown which contains a list of all Swagger documentation in the project. I’ve purposefully named it differently to the c.SwaggerDoc method so that you can see the difference in the output. 

Testing the application 

If you build and run the application, then navigate to localhost: https://localhost:xxxx/swagger.index.html you should see the swagger UI displaying together with information about the WeatherForecast endpoint. 

Graphical user interface

Description automatically generated

You can use the Try it out button to test the API without having to use an external tool. After clicking the button, click Execute. If the API took parameters or a more complex request body, we would be able to add this before executing the request. 

You can see the curl command which would be executed to make the request, as well as the request URL, server’s response, response code, response headers and the schema of the data. 

Graphical user interface, text, application

Description automatically generated
Graphical user interface

Description automatically generated

Leave a comment

Your email address will not be published.