Swashbuckle has been the de facto standard for generating OpenAPI documents for ASP.NET APIs for a long time. Many teams use it for documenting APIs for consumers, generating API clients, configuring API gateways, and of course testing and debugging via the Swagger UI.
However, an announcement earlier this year has stirred things up a bit:
Swashbuckle.AspNetCore is being removed in .NET 9. The ASP.NET Core team is going to remove the dependency on Swashbuckle.AspnetCore from the default ASP.NET Core web API template and replace it with their own OpenAPI document generator: Microsoft.AspNetCore.OpenApi. Their reasoning: Swashbuckle was no longer being actively maintained. PRs were not merged, there was no support for .NET 8 and there were no releases for more than a year.
The choice for Microsoft.AspNetCore.OpenApi does not come as a surprise because it’s not a new package. It has been launched with .NET 7 and is already part of the template for Minimal APIs, in combination with Swashbuckle.AspnetCore.
The Microsoft package scope, however, is different from Swashbuckle’s since it provides no UI. Many teams still rely on Swagger UI because it’s an accessible way to start debugging and local testing.
Microsoft is pushing for an alternative in the form of the Endpoints Explorer and .http files. While this is a good alternative and maybe the new future standard for .NET, it still lacks some developer productivity features that many rely on with Swagger UI, particularly when it comes to response types and authentication with external identity providers.
I have no doubt that these features will be added since they are already available in the Visual Studio Code REST Client extension, which is the inspiration for the Visual Studio version of .http files. However, in its current state it just feels too early to go all in on .http files, especially for teams building more complicated APIs.
Since OpenApi is an open format, you could also take the JSON API description generated by Microsoft.AspNetCore.OpenApi, and plug it in a Swagger UI competitor, such as Scalar. Nick Chapsas discusses it here, in his slightly overdramatic video on the subject.
The thing is, this is exactly what the Swagger UI part of Swashbuckle is doing, but Scalar still needs to catch up on all Swashbuckle and Swagger UI features that have been added over the years.
Obviously you do not need to rely on a solution inside your Visual Studio IDE. There used to be a time where Postman was a good alternative but in the last few years it has degraded into a bloated mess with forced accounts for their cloud service and making it very difficult to save collections to your Git repo. Competitors such as Bruno, are promising but are still developing important features, such as out of the box authorization support.
And, if you want to reduce cognitive load in your developer experience, relying on more external tools will probably not be helpful.
Something interesting has happened since Microsoft’s announcement. The Swashbuckle project has sprung back to life with the formation of a new core team. (Note that the original core maintainer of Swashbuckle puts the ‘blame’ of it being unmaintained fully on himself whilst this is just another example of the Open Source Sustainability Crisis).
New releases have been pushed regularly, .NET 8 support has been added, old PRs are merged or cleaned up and many issues have been addressed. A great accomplishment by the new team.
So, where does that leave us? For now, it seems too early for most developers to switch to Swashbuckle and Swagger UI alternatives, especially if you’re working with more complex APIs. While Swashbuckle and Swagger UI may feel a bit old-fashioned and hard to configure, sometimes ‘boring’ tech is exactly what you need, as long as it is actively maintained.
If you’re working on a simple API or just starting a new project, it’s definitely worth exploring .http files, as they show a lot of potential. However, if you’re happily using Swashbuckle, there’s no rush to migrate. Upgrading to .NET 9 won’t pose any issues for your existing projects, as Swashbuckle is only being removed from templates for new ASP.NET projects.