Integrating Swagger UI, Scalar and ReDoc into a .NET 9 Web API

5 min readApr 17, 2025

Swagger UI, Scalar and ReDoc are OpenAPI UI tools that generate documentation for Web APIs. In this article, I present how to use and integrate these tools into a .NET 9 Web API.

Before diving into each of these tools, it’s important to know about the OpenAPI Specification (OAS), which is a standard format for describing the structure of APIS. Tools like Swagger UI, Scalar and ReDoc can read an OpenAPI file and generate documentation based on it.

Differences between them

Before diving into the code, let’s analyse which are the differences between these three tools.

Swagger UI: is the most widely used OpenAPI UI tool. It offers a clean and simple interface that allows users to interact with API endpoints directly from the browser, by sending requests and viewing responses Note that there is a difference between Swagger and Swagger UI: Swagger is a set of tools and specifications to design, build, document Web APIs, while Swagger UI is a tool from Swagger that renders OpenAPI specification in a web based UI.
Scalar: is a modern documentation UI. It also allows users to test endpoints and inspect responses interactively within the browser. A nice extra feature offered by Scalar is the code snippet generator, which provides a ready to use code to call the endpoint, and it is presented in different programming languages and HTTP clients.
ReDoc: focus on providing a clean and elegant read-only interface for API documentation. Unlike Swagger and Scalar, it does not support interactive requests, making it ideal for static documentation needs.

Common Configuration

Regardless of which tool you decide to use, there are configurations and packages that are common to all of them. So, let’s start with these common configurations.

The first thing to do is install the following NuGet package:

Microsoft.AspNetCore.OpenApi
dotnet add package Microsoft.AspNetCore.OpenApi --version 9.0.4

dotnet add package Microsoft.AspNetCore.OpenApi --version 9.0.4

Then in the Program.cs file, add the following lines:

services.AddOpenApi();

// ...

app.MapOpenApi();

Now we can proceed with the specific configurations.

Swagger UI

To install Swagger UI, install the following packages via NuGet packages:

Swashbuckle.AspNetCore
dotnet add package Swashbuckle.AspNetCore --version 8.1.1

Then in the Program.cs file, add these lines:

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/openapi/v1.json", "Open API - Swagger");
});

Run your app and open your app URL in the browser, and add /swagger at the end of the URL, and you can execute the request to the API endpoint:

You can also see the Schemas used by the API, which represent the structure of the data that the API interacts with:

Scalar

To add Scalar to your Web API, install the following NuGet package:

Scalar.AspNetCore
dotnet add package Scalar.AspNetCore --version 2.1.15

In the Program.cs file, add the following lines:


 app.MapScalarApiReference(options =>
 {
     options
     .WithTitle("Open API - Scalar")
     .WithTheme(ScalarTheme.BluePlanet)
     .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
 });
// Or use only this line for default config: app.MapScalarApiReference();

Run your app and open your app URL in the browser, and add /scalar at the end of the URL. Then click on the endpoint (in this example the GET /WeatherForecast), and click on Send, and you will see the response:

Scalar also have a code snippet generator of how to call the endpoint using different programming languages and HTTP clients (you can literally copy and paste the code sample to your app). In this example, you can see examples in C# with HttpClient and in GO:

You can also see the Models, which are the structured representations of the API’s data:

ReDoc

To add ReDoc to your Web API, install the following NuGet package:

Swashbuckle.AspNetCore.ReDoc
dotnet add package Swashbuckle.AspNetCore.ReDoc --version 8.1.1

In the Program.cs file, add the following lines:

app.UseReDoc(options =>
{
  //options.RoutePrefix = "docs"; // change relative path to the UI
    options.DocumentTitle = "Open API - ReDoc";
    options.SpecUrl("/openapi/v1.json");
});

Run your app and open your app URL in the browser, and add /api-docs at the end of the URL, and you can see the Schema and the endpoints of the API:

Refactoring the Configuration

As a good practice, you can also separate this configuration into a configuration file. For that, create a file in your project for it:

In this file, add two extension methods:

In your Program.cs file, call these methods:

Configuring the application to automatically open the browser

You can also configure your app to automatically open the browser once the app starts. For that, go to the launchSettings.json file in the Properties folder and set:

The launchBrowser property to true
Add the launchUrl property, informing which UI Tool you would like to use (swagger, scalar, api-docs):

"https": {
  // ...
  "launchBrowser": true,
  //"launchUrl": "swagger",
  "launchUrl": "scalar",
  //"launchUrl": "api-docs", // For ReDoc
  // ... 
}

Conclusion

As presented, integrating Swagger, Scalar, and ReDoc is easy and simple. Choosing which one to use depends on your audience and what you need. Swagger offers a clean, simple and great UI and it is widely used by developers. Scalar offers a modern interface with great interactive capabilities. ReDoc can be used when you do not need to provide interactivity and only want to present the documentation for your Web API. As presented, you can also include more than one in your project.

This is the link for the project in GitHub: https://github.com/henriquesd/OpenApiToolsDemo