Adding Swagger UI to .NET Aspire on Linux

Installing the Swashbuckle NuGet Package

[0:38 - 1:35] Tim opens the Tiny Ticket project in VS Code and navigates to the API service's Program.cs. The API already has a GET /api/tickets endpoint from the previous episode, but calling it required manually constructing the URL. To add a proper test interface, the first step is installing the Swagger UI package.

Right-click the API project, select "Add NuGet Package," and search for Swashbuckle.AspNetCore.SwaggerUI. Tim installs the latest version (10.1.7 at the time of recording). After installation, the package reference appears in the project file. No other dependencies are needed because the project already includes OpenAPI support through the default Aspire service configuration.

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

Configuring Swagger UI in Program.cs

[1:35 - 3:12] With the package installed, the configuration goes into the development-only block of Program.cs. The project already has app.MapOpenApi() registered, which generates the OpenAPI specification file at runtime. Swagger UI simply needs to know where that file lives and what to label the endpoint group.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

The SwaggerEndpoint call points to the OpenAPI specification that .NET generates automatically. The second parameter is a display name that appears in the Swagger UI dropdown. Tim emphasizes that these three lines are the entire Swagger setup. You could add more configuration to customize the UI, group endpoints, or add authentication headers, but for a development testing tool, the defaults are sufficient.

One detail worth noting: since .NET 9, new API projects no longer include Swagger by default. Microsoft separated the concerns by shipping OpenAPI as the standard and letting developers choose their preferred UI layer. Swagger, Scalar, and other tools all consume the same OpenAPI spec file, so you are not locked into any particular viewer.

Running and Verifying the Swagger Interface

[3:12 - 6:07] After saving, Tim launches the project through the Run and Debug panel. Once the Aspire dashboard loads and the API service shows as running, he navigates to the API's URL and appends /swagger to the path.

The Swagger UI loads with the "Ticket App API v1" label and lists the available endpoints. The root endpoint (/) returns a simple health message, and /api/tickets returns the ticket data from the database.

Tim clicks "Try it out" on the root endpoint and executes it. The response comes back with a 200 status and a confirmation message. Then he moves to the /api/tickets endpoint and hits execute, which is where the troubleshooting begins.

The first attempt fails with a connection error: "A network-related or instance-specific error occurred when establishing connection to the SQL server." The database container had not started after a machine reboot. Tim opens Portainer, finds the SQL Server Docker container, and starts it. After the container finishes initializing, he returns to Swagger and executes the request again. This time, the response returns a 200 with the three test tickets stored in the database.

That sequence is a practical reminder that integration tests against real infrastructure will surface issues that unit tests and mock data cannot. The database container is not set to auto-start on boot, which means the first API call after a reboot will fail unless you verify the container state first.

What Comes Next: CRUD Endpoints

[6:07 - 7:20] Tim previews the upcoming episodes in the series. The Tiny Ticket API currently has only the GET /api/tickets endpoint, which maps to the spTickets_GetAll stored procedure. The remaining stored procedures in the database (Get by ID, Insert, Update, Delete) each need a corresponding API endpoint with the correct HTTP verb: GET for retrieval, POST for creation, PUT for updates, and DELETE for removal.

He notes that each endpoint follows the same pattern and is straightforward to implement, but the upcoming videos will cover them individually so that each piece is easy to reference independently. The choice to break the series into small, focused episodes means you can jump directly to the endpoint type you need without scrubbing through a longer video.

Conclusion

[7:20 - 7:24] Adding Swagger UI to a .NET Aspire project on Linux requires one NuGet package and three lines of configuration in Program.cs. The OpenAPI spec file is already generated by the default Aspire service setup, so Swagger only needs a pointer to that file and a display name. From there, every endpoint in the API is testable through the browser without building a separate client.

The database connection issue Tim encountered after rebooting reinforces a practical point: when your development stack includes containers, verify they are running before testing API endpoints. Swagger gives you a fast feedback loop for that verification.

Series navigation: This article is part of the C# on Linux series building the Tiny Ticket app. Previous: Setting Up .NET Aspire on Linux. Next: Adding a Get By ID Endpoint.

Example Tip: If you prefer a different OpenAPI viewer over Swagger, install a package like Scalar or RapiDoc and point it at the same /openapi/v1.json endpoint. The spec file is UI-agnostic, so you can swap viewers without changing your API configuration.

Watch full video on his YouTube Channel and gain more insights on building APIs in the C# on Linux series.