Modernizing API Docs: OpenAPI and Swagger UI in .NET 9

With the release of .NET 9, developers are encountering a notable evolution in how API documentation and exploration are handled. The familiar reliance on Swashbuckle for both OpenAPI document generation and Swagger UI presentation has given way to a more streamlined, native framework approach. This shift marks a significant step towards a lighter, cleaner, and potentially faster development experience.

The New Paradigm: Decoupled and Efficient

Microsoft has intelligently decoupled the core functionalities, introducing a built-in mechanism for OpenAPI document generation directly within the .NET framework. While AddSwaggerGen() and UseSwagger() might no longer be the default in new project templates, the robust and user-friendly interface of Swagger UI is certainly not obsolete.

Developers can now leverage the framework’s efficient OpenAPI generation and still utilize Swashbuckle.AspNetCore.SwaggerUI to display these documents. This setup provides the best of both worlds: a powerful, native backend for API specification generation, combined with the interactive and visually appealing Swagger UI frontend.

Implementing a Modern Setup with JWT Authentication

Let’s explore how to integrate this modern configuration, ensuring your /swagger endpoint is fully operational and supports JWT Bearer authentication.

1. Service Configuration for OpenAPI
You’ll begin by registering the built-in OpenAPI services using an extension method, for example, AddOpenApiConfiguration. A critical component here is the inclusion of a custom DocumentTransformer. This transformer, like a BearerSecuritySchemeTransformer, is essential for injecting security definitions into your OpenAPI document. It programmatically adds the JWT Bearer security scheme, which enables the “Authorize” button in Swagger UI and correctly annotates your API operations for authentication.

2. Configuring Swagger UI
Next, another extension method, such as UseOpenAPIWithSwagger, will be used to configure Swagger UI. In this method, you specify that Swagger UI should read its API definition from the framework-generated /openapi/v1.json endpoint. This is also where you can customize various Swagger UI options, such as enabling persistent authorization, displaying request durations, and controlling the default expansion of API operations for a tailored user experience.

3. Minimal Program.cs Integration
The beauty of this approach lies in its simplicity within your Program.cs file. After setting up your controllers and configuring JWT Bearer authentication (by adding services for JwtBearerDefaults.AuthenticationScheme and defining token validation parameters), you simply call your custom AddOpenApiConfiguration() and UseOpenAPIWithSwagger() extension methods. This minimalist setup ensures that your API documentation is generated efficiently and presented beautifully, with full support for authenticated endpoints.

Required NuGet Packages:
To implement this setup, you’ll typically need to include the following NuGet packages in your project file:
* Microsoft.AspNetCore.OpenApi (for the native OpenAPI generation)
* Swashbuckle.AspNetCore.SwaggerUI (for the interactive UI frontend)

Advantages of the .NET 9 Approach

This refined methodology offers several compelling benefits for ASP.NET Core developers:

• Reduced Reflection Overhead: By utilizing the framework’s native OpenAPI generation capabilities, you significantly reduce the reflection-based processing often associated with older Swashbuckle implementations, leading to potentially faster application startup times.
• Cleaner Codebase: The separation of concerns and the use of built-in features reduce the need for extensive AddSwaggerGen configurations or specialized Swashbuckle filters, resulting in a more concise and maintainable codebase.
• Alignment with Modern .NET: This approach aligns seamlessly with the evolving direction of .NET development, prioritizing native capabilities for core functionalities over relying solely on third-party solutions.
• Enhanced Performance: A lighter document generation process contributes to improved application performance and a more responsive development environment.

Conclusion

In summary, while the traditional Swashbuckle.AspNetCore package might be stepping back from its all-encompassing role in .NET 9 templates, the functionalities it provided are far from obsolete. Instead, they have evolved into a more elegant, efficient, and deeply integrated solution. By embracing Microsoft’s built-in OpenAPI generation alongside the proven capabilities of Swashbuckle.AspNetCore.SwaggerUI, developers can continue to deliver rich, interactive API documentation with robust JWT authentication support. This represents a significant step forward, fostering a leaner, simpler, and ultimately more developer-friendly ecosystem for ASP.NET Core API development.