Built-in OpenAPI Document Generation with .NET 9 — No more SwaggerUI! 👋
What’s Swagger UI?
Swagger UI is an open-source tool that automatically generates an interactive, web-based documentation interface for WebAPIs.
It supports OpenAPI standards. It was very popular tool among the ASP.NET Core developers from 2020 to 2024.
Because it was a built-in tool comes with ASP.NET Core default templates.
We liked this tool because it was the first tool that allows us to make WebAPI calls for testing.
Now it provides paid services as well as free ones.
Previously, Swagger was included by default from .NET 5 to .NET 8 in .NET web templates.
What’s OpenAPI?
OpenAPI is a standard specification for defining REST APIs.
The official website is https://www.openapis.org/.
Microsoft is now using OpenAPI and here is the official documentation 👉 https://aka.ms/aspnet/openapi
Replacement of Swagger UI with OpenAPI
Swagger UI is no longer integrated into NET 9, as Microsoft wants a solution with first-class support, better control, and enhanced security. As you see in the below screenshot, Microsoft declares that it's already removed.
Why is Swagger Removed from .NET 9?
In March 2024, the ASP.NET Core team announced that they are removing the Swashbuckle.AspNetCore
dependency from web templates from .NET 9 release.
This decision was influenced by the project's lack of active maintenance and the absence of an official release for .NET 8.
Microsoft team created a new package Microsoft.AspNetCore.OpenApi
. It provides built-in OpenAPI document generation just like Swagger. So Microsoft doesn't depend on external tools. Because in every .NET release, they need to ask the owners of the external tool libraries to align with their new version. And sometimes these library owners cannot update their code-base according to the recent .NET changes. And it is becoming harder for Microsoft to support the 3rd party libraries under these circumstances. Basically reducing 3rd party dependencies will help Microsoft fast release cycles.
I read Reddit, GitHub discussions and YouTube reviews about this topic. As I see community members expressed concerns about the inactivity of Swashbuckle and they are discussing alternatives like contributing to or forking the project. The Microsoft team also contacted the owners of Swashbuckle and NSwag to explore potential collaborations and ensure a smooth transition for developers.
In the below GitHub issue, you can see the details of this decision:
Jeremy -Product Manager- at Microsoft, answers why they took this decision in this post.
As a summary;
The change is due to a lack of maintenance of the Swagger library, although it has seen some recent updates. This aims to reduce dependency on external tools and provide a streamlined, out-of-the-box experience for generating OpenAPI documentation for ASP.NET Core Web APIs.
What are the Benefits of the New OpenAI Package?
Native Support and Reduced Dependency
The new Microsoft.AspNetCore.OpenApi
package provides first-class citizen support for OpenAPI. It reduces reliance on external tools like Swashbuckle or NSwag for basic documentation needs. The native implementation leverages source generators to reduce runtime overhead.
Simplified Configuration
No need extra setup or 3rd party integrations. Just by defining controllers and endpoints, ASP.NET Core automatically generates OpenAPI specifications.
Well Integration with Minimal APIs
Minimal APIs introduced in .NET 6. There's an optimized built-in support for Minimal APIs. It automatically adds metadata for routes, request parameters, and responses.
Compatibility with Existing Tools
You can still use the output of OpenAPI with Swagger or NSwag... So it doesn't mean that in this case you have only one option when you use OpenAPI.
How to Use the New OpenAPI in .NET9?
When you create a new ASP.NET Core project, you can see the below checkbox to add OpenAPI.
I created a new .NET 9 web project, I saw that OpenAPI had already been added.
Add OpenAPI Support For Your Existing Project
Upgrade your project to .NET 9 and add the required NuGet package Microsoft.AspNetCore.OpenApi
dotnet add package Microsoft.AspNetCore.OpenApi
Add the following services and middleware in Program.cs
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(); //<<-----
var app = builder.Build();
app.MapOpenApi(); //<<-----
app.MapGet("/", () => "Test");
app.Run();
Your OpenAPI document URL is https://localhost:7077/openapi/v1.json
Change the port to your active port. This is how it looks like:
Alternative 3rd Party Tool: Scalar
Scalar is an open-source API platform for RestAPI documentation. Also, it provides an interface for interacting with RESTful API. Generates interactive and user-friendly API documentation. Supports OpenAPI and Swagger specifications. It’s open-source with 7K stars on GitHub.
See the repo 👉 https://github.com/scalar/scalar.
That's all from the replacement of Swagger in .NET 9.
Happy coding 👨💻
References
Comments
omerkaya 4 weeks ago
Although it has been removed from the default template, will Swagger UI still be supported in .NET 9?
sakurasponge1220@gmail.com 4 weeks ago
Swagger UI is not the same as OpenApi. Swagger UI is a UI interface generated from the JSON format produced by OpenApi (formerly known as Swagger). Microsoft has now removed support for Swagger UI and has instead implemented the generation of OpenApi.
omerkaya 2 weeks ago
Yeah I mean Swagger UI. Because I think both Swagger and Microsoft (builtin) generates same JSON format? So, maybe Swagger UI can use the builtin OpenApi json? By the way, has Microsoft removed Swagger as a default package or removed all support for Swagger? Isn't it possible for Swagger to use new builtin json? (If Scalar can use it, maybe Swagger UI can use it also)
saeedrabid 2 weeks ago
I think we should have Scalar Module in ABP Framework like AbpSwashbuckleModule