.NET 9 Revolutionizing documentation of APIs : From Swashbuckle to Scalar 🚀

Abstract

API documentation is the backbone of modern software development. With .NET 9's shift from Swashbuckle to Microsoft.AspNetCore.OpenApi, developers need new strategies to stay efficient. This article explores these changes and introduces Scalar, a game-changer for API documentation.
This article delves into the evolution and integration of Swagger in the ASP.NET ecosystem, with a focus on the new developments in .NET 9. It traces Swagger’s journey from its origins as an open-source project to its widespread adoption as the de facto tool for API documentation, testing, and client code generation in the .NET space. As .NET Core matured, Swagger tools like Swashbuckle streamlined the process of adding interactive documentation and OpenAPI support to ASP.NET applications. However, with the release of .NET 9, Swashbuckle.AspNetCore is being deprecated in favor of the Microsoft.AspNetCore.OpenApi library. The article provides practical guidance on how to incorporate Swagger into .NET 9 Web APIs and highlights the shift towards more modern, efficient tools. It also introduces Scalar .NET, an innovative platform that enhances Swagger with a sleek user interface and first-class OpenAPI support. Offering step-by-step instructions and code examples, this article serves as a comprehensive resource for developers looking to modernize their API documentation strategies in .NET 9.

The Story of Swagger
The story of Swagger in ASP.NET is intertwined with the rise of API-driven development and the need for better ways to document, test, and interact with APIs. Here’s a breakdown of how Swagger became a key tool for ASP.NET developers:

The Rise of APIs
As RESTful APIs became central to modern application development, developers faced the challenge of creating clear and consistent documentation. Traditional documentation methods were error-prone and difficult to maintain, especially for large APIs.
Swagger emerged in 2011 as an open-source project by Tony Tam. It aimed to standardize how APIs were described, enabling tools to generate interactive documentation, client SDKs, and server stubs automatically.

Early Adoption in .NET
ASP.NET developers quickly saw the potential of Swagger. However, the integration was manual at first, requiring developers to write Swagger specification files (in JSON or YAML) by hand. This process was tedious and discouraged adoption.

Swashbuckle Makes Swagger Seamless
Swashbuckle, created by Richard Morris, was a game-changer for ASP.NET developers. It provided an easy way to integrate Swagger into ASP.NET projects, automatically generating Swagger JSON from your Web API controllers and routes.
Swashbuckle added features like:

• Automatic Documentation: Generating API documentation directly from code, using XML comments and data annotations.
• Swagger UI Integration: Embedding an interactive API documentation interface directly into your app.
• Customizability: Allowing developers to extend and tweak the Swagger output.

ASP.NET Core Era
When ASP.NET Core was introduced in 2016, it was built with modularity and flexibility in mind. This made integrating Swagger tools even more straightforward. Swashbuckle adapted to ASP.NET Core and became the de facto standard for Swagger integration.
Key features during the ASP.NET Core era:

• OpenAPI Specification: Swagger transitioned to the OpenAPI standard in 2015, ensuring broader industry adoption.
• Improved Middleware Support: ASP.NET Core’s middleware architecture made it simple to add Swagger generators and UI middleware.
• API Versioning Support: Tools like Swashbuckle and NSwag supported multiple API versions, catering to evolving APIs.

Expanding Swagger Ecosystem
Today, ASP.NET developers have multiple options for working with Swagger:

• Swashbuckle: The most popular and feature-rich solution for ASP.NET Core.
• NSwag: Another powerful tool that supports OpenAPI and adds features like client code generation for TypeScript and C#.
• Azure Integration: Swagger/OpenAPI specifications are often used to integrate APIs with Azure API Management. Swagger’s Role in Modern Development Swagger (or OpenAPI) in ASP.NET projects plays a pivotal role in:
• Collaboration: Bridging the gap between developers, testers, and stakeholders.
• Automation: Generating client SDKs and testing tools automatically.
• Developer Experience: Allowing developers to explore and test APIs interactively through tools like Swagger UI.

Swashbuckle.AspNetCore is being removed in .NET9 (Is Swashbuckle is deprecated ?)
“The ASP.NET Core team began shipping web API templates with a dependency on Swashbuckle in the .NET 5 timeframe. The decision allowed the team to provide built-in support for OpenAPI, a language-agnostic, platform-neutral representation of web-based APIs that contains everything needed to discover and interact with HTTP-based service endpoints. You may be more familiar with the name “Swagger” that refers to a set of tools for working with OpenAPI documents. The information in the OpenAPI document enables scenarios like client code generation, stubbing server code, creating documentation and dynamically producing a web-based UI to interactively test the API. It also is heavily used in artificial intelligence applications to provide prompts that describe the API for use by generative AI.
Swashbuckle is a great project, and we appreciate the time and effort its owner and community contributors have put into it. The project is no longer actively maintained by its community owner. Issues have not been addressed or resolved, and there is not an official release for .NET 8. The ASP.NET Core team will provide a solution for this in the .NET 9 release. The plan is to remove the dependency on Swashbuckle.AspnetCore from the web API template and extend the capabilities introduced with Microsoft.AspNetCore.OpenApi to provide OpenAPI document generation.”
For more details on the deprecation of Swashbuckle.AspNetCore, refer to this GitHub issue:

The Future of Swagger
With Microsoft continuously improving ASP.NET Core and OpenAPI becoming the industry standard, Swagger was expected to remain an integral part of the ecosystem. Features like minimal APIs in ASP.NET Core 6+ have made it even easier to integrate Swagger for lightweight and performant APIs. In spite of removing Swagger from Webapi samples it’s still updating and available to use.

How to add Swashbuckle (in practice) to the .Net9 webapi
I’l tell you how to add Swagger into your .Net Web API project using SwashBuckle
Before commencement ensure that .Net version 9 SDK is installed on your system properly

First make a new webapi project with this comamnd
Dotnet new webapi -n OpenApi-Swagger-Scalar

Then Open your project in VsCode
Next right click on an empty area in your project explorer and click on Open In integrated terminal
Next run this command
dotnet add package Swashbuckle.AspNetCore

Now it’s time to configure Swagger in Program.cs

(You see something about OpenApi in your program.cs
builder.Services.AddOpenApi();
app.MapOpenApi();
We will We will discuss that topic later in this topic)

Add these line below : builder.Services.AddOpenApi();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Add these lines below app.MapOpenApi()
app.UseSwagger(); // Enable the Swagger JSON endpoint
app.UseSwaggerUI(); // Enable the Swagger UI

Run Your Project and open the uri :
http://localhost:{your_port}/swagger/index.html
Or just navigate to /swagger
For example
http://localhost:5000/swagger

Congrats! You have SwashBuckle Swagger in .Net9 again!

The Story of OpenApi
OpenAPI, formerly known as Swagger, is a specification for describing REST APIs. It allows developers to define the structure of their APIs, including endpoints, operations, parameters, and authentication methods, in a format that is both human-readable and machine-readable.
The OpenAPI Specification (OAS) was originally developed by Tony Tam in 2010 as part of the Swagger project. The goal was to create a standard way to describe APIs, making it easier for developers to design, build, document, and consume APIs. In 2015, the Swagger project was donated to the OpenAPI Initiative, a consortium of industry leaders, and the specification was renamed to OpenAPI.
Swagger tools, such as Swagger Editor, Swagger UI, and Swagger Codegen, were built around the OpenAPI Specification to help developers work with APIs more efficiently. These tools allow developers to write OpenAPI definitions, generate interactive API documentation, and create server stubs and client libraries in various programming languages.
The ability of APIs to describe their own structure through OpenAPI has revolutionized API development, enabling better collaboration, automation, and integration across different tools and platforms.
Let’s tell you the first secret 😊
In the test project from previous section you had these two lines in your Program.cs

builder.Services.AddOpenApi();
app.MapOpenApi();

When debugging your test project let’s navigate to this link
http://localhost:{your_port}/openapi/v1.json
for example
http://localhost:5000/openapi/v1.json
You can see all documents about all your apis.

OpenAPI vs. Swagger
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. You can read more here : microsoft.com

Use SwaggerUI with the power of OpenApi json
So when we already have OpenApi as below
app.MapOpenApi();
There is another choice, swagger can benefits from OpenApi documents to generate it’s UI instead of swagger json endpoint
Thus we can remove this line
app.UseSwagger();
And Instead of this line
app.UseSwaggerUI();
You can use like this
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/openapi/v1.json", "Your Custom Title");
});

Scalar, A game changer!
Scalar .NET is an open-source API platform that provides a modern REST API client and beautiful API references with first-class OpenAPI/Swagger support. The Scalar.AspNetCore package makes it easy to integrate the Scalar API reference into your .NET applications.
You can read more here.

How to add Swashbuckle (in practice) to the .Net9 webapi
Install the package: Use the following command to add the Scalar.AspNetCore package to your .NET sample project:
dotnet add package Scalar.AspNetCore

Add this line above your Program.cs to as the namespace
using Scalar.AspNetCore;

Ensure that you have these lines in your program.cs
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
app.MapOpenApi();

Now add this line to the Program.cs
app.MapScalarApiReference();

When debugging your test project let’s navigate to this link
http://localhost:{your_port}/scalar/v1
for example
http://localhost:5000/scalar/v1
You can see a new modern and pretty cool UI to test your apis :

Time to tell you the second secret 😊
Instead of this line
app.MapScalarApiReference();

let’s use something like this
app.MapScalarApiReference(options =>
{
options
.WithTitle("Your Custom Title")
.WithTheme(ScalarTheme.Mars)
.WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
});

Boom !!!

• Now You have your custom title
• You have an amazing theme
• You have C# codes as the default

All solutions
Now you have all this links for test with these lines of code existing in the Program.cs
builder.Services.AddOpenApi();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
app.MapOpenApi();
app.UseSwagger(); // Enable the Swagger JSON endpoint
app.UseSwaggerUI(); // Enable the Swagger UI
app.MapScalarApiReference();

Json Based Document for apis
http://localhost:5000/openapi/v1.json
http://localhost:5247/swagger/v1/swagger.json
UI based
http://localhost:5000/swagger/index.html
http://localhost:5000/scalar/v1

Summary
This article explores the evolution of Swagger in the ASP.NET ecosystem and its integration with .NET 9, focusing on OpenAPI and the Scalar platform.
It begins by detailing the history of Swagger, its emergence as an open-source tool to standardize API documentation, and its early adoption by ASP.NET developers. The article highlights how tools like Swashbuckle made Swagger easier to integrate with ASP.NET Core, automating API documentation and enhancing the developer experience. As .NET Core evolved, Swagger became a key tool for API documentation, testing, and client code generation.
With the release of .NET 9, Swashbuckle.AspNetCore is being deprecated, and the ASP.NET Core team plans to extend the Microsoft.AspNetCore.OpenApi library. The article provides practical steps for adding Swagger (via Swashbuckle) to a .NET 9 Web API project and discusses the removal of Swagger in Web API templates, suggesting alternatives for API documentation.
The article also introduces Scalar .NET, a modern platform that enhances Swagger with a beautiful UI and OpenAPI support. It shows how to integrate Scalar into a .NET project, offering a more polished and customizable API reference solution.
In summary, the article covers the history, evolution, and future of Swagger in the .NET ecosystem, along with practical guidance on using both Swagger and Scalar for efficient API documentation in .NET 9. And With the tools and insights provided, you're now ready to modernize your API documentation in .NET 9. Whether leveraging Scalar or sticking with OpenAPI, the key is to adapt and stay ahead of evolving standards.

Source codes are available for download here :
Github : https://github.com/zandiarash