NO SWAGGER? NO PROBLEM! OpenAPI Made Easy in .NET 9

Summary

In .NET 9, the default Swagger package has been replaced with a new Open API package. This tutorial explores how to integrate various Open API UI alternatives like Swagger, Redoc, and Scaler into a .NET Aspire application. It covers setting up the Open API document, adding these UI options, and customizing API resources within .NET Aspire to include easy access to documentation. The video demonstrates step-by-step how to install necessary NuGet packages, configure APIs, and create reusable commands to streamline accessing the documentation interfaces, enhancing user experience in a .NET 9 environment.

Takeaways

• 😀 Swagger is no longer the default OpenAPI package in .NET 9, and a new package, Microsoft.AspNetCore.OpenAPI, is responsible for generating OpenAPI documentation.
• 😀 The new service `AddOpenAPI` and middleware `MapOpenAPI` replace the previous Swagger configuration in .NET 9.
• 😀 Developers can install Swagger, Redoc, or Scaler UI NuGet packages to provide a user interface for interacting with OpenAPI documentation.
• 😀 The `Swagger UI` NuGet package can be installed to restore the familiar Swagger UI, enabling interactive testing of API endpoints.
• 😀 Redoc offers an alternative UI with an API documentation style, including response schemas and customizable features.
• 😀 Scaler provides additional functionality compared to Swagger, such as code generation for different programming languages and HTTP client examples.
• 😀 A simple method is demonstrated to configure each of the three UI options (Swagger, Redoc, and Scaler) in a .NET 9 application.
• 😀 The user creates a custom command in .NET Aspire to open the Swagger UI via a button on the API service resource.
• 😀 The custom command in Aspire uses the `Process` class to open a new browser tab with the Swagger UI.
• 😀 To make the custom command reusable, the user defines extension methods on the `IRResourceBuilder` to allow for easy integration of Swagger, Redoc, and Scaler UIs.
• 😀 The tutorial concludes with a demonstration of how to add the new UI options to .NET Aspire and use them via custom commands.

Q & A

What is the key change introduced in .NET 9 regarding OpenAPI documentation?

In .NET 9, Swagger has been removed as the default OpenAPI package. Instead, the new `Microsoft.AspNetCore.OpenAPI` package is introduced to generate OpenAPI documents.

How does the new OpenAPI package in .NET 9 differ from the previous default Swagger package?

The new OpenAPI package in .NET 9 generates the OpenAPI document without including a UI by default, whereas Swagger was the previous default package that included both the document and the Swagger UI.

What is the purpose of the `AddOpenAPI` and `MapOpenAPI` methods in .NET 9?

The `AddOpenAPI` method registers the OpenAPI service, and `MapOpenAPI` exposes an endpoint that serves the OpenAPI document. These methods are used to configure the OpenAPI documentation for the API.

Can you still use Swagger in .NET 9, despite it no longer being the default?

Yes, Swagger can still be used by installing the `Swagger UI` NuGet package and configuring it with the OpenAPI document endpoint.

What other OpenAPI UI alternatives are explored in the video?

The video explores two alternatives to Swagger: Redoc and Scaler. Both packages offer user interfaces for viewing and interacting with API documentation.

How do you configure Redoc as an OpenAPI UI in a .NET 9 application?

Redoc can be configured by installing the `Redoc` NuGet package and using the `UseRedoc` method to define the middleware, specifying the OpenAPI document URL.

What is Scaler and how is it different from Swagger and Redoc?

Scaler is an OpenAPI UI that provides additional functionality, such as displaying HTTP client examples in different programming languages (e.g., C# and Curl). It also provides model documentation.

What is the process for integrating these OpenAPI UIs into a .NET Aspire project?

In .NET Aspire, you can integrate OpenAPI UIs by defining custom commands for each UI (Swagger, Redoc, Scaler) in the API service resource. These commands can open the respective UI in a browser when clicked.

How can you create reusable custom commands in .NET Aspire?

Reusable custom commands in .NET Aspire are created by defining methods that include arguments for the UI names, display names, and routes. These methods can be called for different OpenAPI UIs, allowing the user to open the respective UI in the browser.

What does the custom command for opening the Swagger UI in .NET Aspire look like?

The custom command for Swagger UI involves defining an async method that retrieves the API endpoint URL, constructs the full URL for the Swagger UI, and uses `Process.Start()` to open it in a new browser tab.