Integration of Swagger for API documentation in .NET Core

Overview

In the world of software development, efficient communication is key, and clear and concise API (Application Programming Interface) documentation is an important part of that. When it comes to API documentation, the OpenAPI standard is a benchmark in the industry. It simplifies the process of creating user-friendly and easily understandable APIs.

By implementing the OpenAPI standard, you can leverage several key benefits of effective API documentation:

1. Facilitated integration and better understanding. Well-designed documentation helps developers understand how to use the API. As a result, the process of integration becomes much easier and faster.
2. Guidance for developers. It serves as a comprehensive guide for developers as it offers detailed instructions and practical examples on how to utilize the API effectively.
3. Support and maintenance. Well-developed documentation helps with ongoing support and maintenance, reduces frequently asked questions, and simplifies troubleshooting.
4. Communication tool. Good documentation is a bridge between API developers and consumers. It means that everyone can stay well aware of the available functionality.
5. Ease of use. With detailed examples, documentation ensures better access to APIs and their broader usability.

Swagger: A Comprehensive Toolset

Swagger is an API documentation toolkit developed by SmartBear Software. It provides a range of core functionalities to help produce and maintain clear and interactive API documentation. What does it offer?

• Swagger Editor. It is an easy-to-use browser-based editor for creating OpenAPI specifications.
• Swagger UI. This is a web-based API testing & exploring interface that can be used to check API behavior.
• Swagger Codegen. This flexible tool for OpenAPI specification is intended for generating API documentation, server stubs, or client libraries.

The use of Swagger can drastically improve the quality of API documentation. It facilitates better comprehension and discoverability, which results in more efficient application of APIs.

How to set up Swagger in a .NET Core API

Here’s a brief guide that will help you to organize your work with Swagger,

Add the Swashbuckle.AspNetCore NuGet Package

This package provides the necessary tools to integrate Swagger into your .NET Core API. Navigate to your project directory and run the following command:

Alternatively, you can use the NuGet Package Manager in Visual Studio to search for and install the package.

• Right-click on the project in the Solution Explorer and select Manage NuGet Packages.
• Set the package source to nuget.org.
• In the Browse tab, enter Swashbuckle.AspNetCore in the search box.
• Select the latest stable version and click Install

Configure Swagger Services

After installing the Swashbuckle.AspNetCore package, the next step is to configure the Swagger services in your .NET Core application. This configuration usually takes place in the Program.cs file in newer versions of .NET, where you set up the Swagger generator.

It’s a good practice to create a defined document in SwaggerGen with a meaningful name, title, and version rather than sticking with the default settings.

The match between name: v1 in SwaggerDoc and Version = v1 in OpenApiInfo is crucial because they both refer to the same API version. This helps Swagger to organize and display the documentation correctly, ensuring that the information users see corresponds to the correct version of the API.

Configure Swagger Middleware

Still in the Program.cs file, the next step is to configure the middleware to serve the generated Swagger JSON endpoint and the Swagger UI.

Integrating Swagger middleware into your .NET Core API project makes creating and displaying API documentation quick and simple. With app.UseSwagger(), you will generate the Swagger JSON documentation. Meanwhile, app.UseSwaggerUI() will provide a user-friendly, interactive interface for exploring and testing your API endpoints. 

For convenience, if you set the RoutePrefix to an empty string (RoutePrefix = string.Empty), you will be able to access the Swagger UI right from the root URL of your application.

Configuring JWT-Based Security for Swagger

Adding Swagger to your .NET Core application necessitates securing not only the Swagger UI but also the underlying API endpoints. This helps to protect sensitive data and ensures that only authorized personnel get access to the API documentation.

This can be done by employing JSON Web Tokens (JWT) for authentication. JWT is a secure way to exchange information between two parties. By combining JWT authentication with Swagger, you can require developers to provide valid JWT tokens to access and interact with your APIs in Swagger.

Once the AddSecurityDefinition and AddSecurityRequirement methods have been defined, Swagger will bring an Authorize button located at the top right corner of its UI. Users of this interface can make use of it and enter a JWT token, which will be sent along with your requests.

Run and Verify

To utilize and verify the configuration of Swagger we are going to use the minimal API endpoint given by Visual Studio’s default template which is specifically the Weather Forecast endpoint. Our Swagger setup can thus be tested on this endpoint so that we can ascertain its flawless functionality. The final form in which Program.cs is as follows:

• Start your application using your IDE or the .NET CLI.
• Open a web browser and navigate to http://localhost:<port (replace <port> with the actual port number your application is running on).
• Navigate to the swagger.json endpoint on http://localhost:<port>/swagger/v1/swagger.json

You should see the Swagger UI displaying your API documentation, including the Weather Forecast endpoint. The interactive interface will allow you to test the /WeatherForecast endpoint and view the sample responses. Additionally, there is an authorization module where you can paste your token to authenticate and test endpoints that require authorization.

Conclusion

With the integration of Swagger into your .NET Core project, your API will become more open and user-friendly. However, simply adding Swagger isn’t sufficient. The adaptation and security of Swagger are crucial for development and production goals. This way, you can guarantee that your API documentation remains extensive, legible, as well as helpful for everyone.