Migrating Away from Swagger in .NET 9: What You Need to Know

.NET 9 brings many enhancements, but one significant change for API developers is the removal of built-in support for Swagger. Swagger has been a crucial tool for API documentation and testing within the .NET ecosystem. However, with .NET 9, Microsoft is shifting away from integrating Swagger directly, pushing developers to consider alternative approaches. In this article, we’ll explore why this change is happening, how it impacts your existing projects, and what steps you can take to ensure a smooth migration.

Why Swagger Is Being Removed from .NET 9

Microsoft’s decision to remove Swagger support is part of a broader shift to streamline the .NET framework and avoid dependency bloat. Swagger, while popular, introduces dependencies and maintenance overhead. By removing it from the core framework, Microsoft aims to allow developers greater flexibility in choosing and configuring API documentation tools independently.

 Alternatives to Swagger in .NET 9

With Swagger’s departure, .NET 9 developers have a few main alternatives for API documentation:

• NSwag: A popular alternative, NSwag provides Swagger-like functionality and integrates well with .NET. It allows for OpenAPI specifications, and you can use it to generate API clients and documentation.
• OpenAPI: OpenAPI is a Swagger-compatible specification that lets you define your API’s structure. With .NET 9, you can implement OpenAPI through other libraries, ensuring your API remains standardized.
• Minimal API Documentation Libraries: For projects that need lightweight documentation without full Swagger/OpenAPI support, minimal API libraries provide simple ways to document API endpoints. 

Steps to Migrate from Swagger to NSwag in .NET 9

Step 1: Remove Swagger Dependencies

The first step in migrating is to remove the Swagger dependencies from your .NET 9 project. Update your project file (.csproj) to remove Swashbuckle.AspNetCore or any other Swagger-related packages.

<ItemGroup>
  <PackageReference Include="Swashbuckle.AspNetCore" Version="x.x.x" />
</ItemGroup>

Remove any Swagger references from this section.

Step 2: Install NSwag

Next, install NSwag by adding it as a package to your project. You can do this via the NuGet Package Manager or by running the following command:

dotnet add package NSwag.AspNetCore

 Step 3: Configure NSwag in Startup.cs or Program.cs

With NSwag installed, configure it in your Startup.cs or Program.cs file to generate and display API documentation.

using NSwag.AspNetCore;
 
public void ConfigureServices(IServiceCollection services)
{
    // Configure NSwag
    services.AddOpenApiDocument(config =>
    {
        config.Title = "My API";
        config.Version = "v1";
    });
}
 
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
 
    app.UseOpenApi(); // Serves the OpenAPI/Swagger documents
    app.UseSwaggerUi3(); // Serves the Swagger UI
    app.UseReDoc(); // Optional: Serves ReDoc UI
 
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Step 4: Test Your New API Documentation

Run your application and navigate to http://localhost:<port>/swagger or http://localhost:<port>/redoc to ensure that your new API documentation is correctly displayed. NSwag should now generate and present your API’s OpenAPI documentation.

Considerations When Migrating

1. Customization: NSwag offers customization options that may differ from Swagger, so take some time to review its documentation to adjust as needed.
2. Client Generation: If you rely on automatic client generation from your API documentation, NSwag supports this but may require configuration adjustments.
3. UI Options: While NSwag includes Swagger UI, consider using ReDoc for a different API documentation experience, especially for internal documentation.

The removal of Swagger in .NET 9 requires a few changes to how you manage API documentation, but NSwag provides a robust, familiar alternative. By following these migration steps, you can ensure a seamless transition and continue delivering well-documented, accessible APIs. As .NET continues to evolve, embracing these changes will help keep your projects streamlined and future ready.

Disclaimer: The views and opinions expressed on this website are solely those of the author and do not necessarily reflect the official policy or position of any employer or organization affiliated with the author.