With the upcoming release of .NET 9, Microsoft is changing how API documentation is handled within the framework. Swagger, the widely used API documentation tool that has been included in Web API templates for years, will be removed from the initial .NET 9 Web API template. Developers will need to change their approach to describing and visualizing API endpoints. But why did this transition occur, and what are the implications for .NET developers?
Why is Microsoft Removing Swagger?
Microsoft has announced that Swagger integration in the standard Web API template would be discontinued due to a lack of ongoing Swashbuckle maintenance. The Swashbuckle.AspNetCorepackage is widely used to generate Swagger documentation. Instead, .NET 9 will ship with the Microsoft.AspNetCore.OpenApilibrary by default, gives a standardized mechanism to build OpenAPI documents directly from the framework.
However, unlike Swagger, which has long provided an interactive UI for displaying API endpoints, Microsoft.AspNetCore.OpenApi doesn’t have a user interface. This means that developers will have to take extra steps if they want to get a visual depiction of their API endpoints.
The easiest way to understand the difference is.
- OpenAPI: Specification
- Swagger: Tools for implementing the specification
What are your Options for API Documentation in .NET 9?
While Microsoft.AspNetCore.OpenApi provides a simple way to build API documents; however, .NET users who are used to Swagger’s appealing UI may need to examine alternative alternatives. Here are a few choices.
- Manually Re-Adding Swashbuckle: Developers that prefer to use Swagger’s interface can still include Swashbuckle.AspNetCore into their .NET 9 projects manually. While this solution preserves the familiar experience, it needs additional setup and does not provide promised long-term support or upgrades because the package is not actively maintained.
- NSwag: An alternative to Swagger, provides similar features and is being maintained. NSwaggenerates OpenAPI specifications and includes a UI for viewing API endpoints, making it a suitable Swagger replacement in.NET 9.
- Scalar and other OpenAPI tools: Scalar and other OpenAPI tools offer powerful capabilities for creating and interacting with OpenAPI standards. While each tool has distinct advantages, it is critical to evaluate them in light of your project’s needs, such as ease of setup, maintainability, and feature set.
- Building Custom Documentation UIs: Using Microsoft.AspNetCore.OpenApi, to create a documentation UI that is suited to their individual needs. OpenApi library provides complete control over appearance and functionality.
Handling Change: Tips for Developers
Many developers may need to modify their present workflows to accommodate this change. Here are a few pointers to help you manage the change successfully.
Plan ahead
Understanding your project’s requirements and selecting a documentation tool before moving to .NET 9 will help ensure a smooth transition. Consider choices such as OpenAPI or NSwag or custom solutions to determine which best meets your team’s needs.
Final Thoughts
Swagger’s removal from the default template in .NET 9 signals a shift in API documentation best practices across the .NET ecosystem. While this shift may appear to be a setback, it also allows for greater freedom and customization in how developers record and expose their APIs. You can continue to deliver clear, intuitive API documentation in .NET 9 by choosing the best solution for your project’s needs, whether it’s NSwag, Swashbuckle, or a custom UI.