Introducción#

Cuando creamos un proyecto Web API en .NET 9, seguro notamos que algo falta: Swagger UI desapareció del template y en su lugar Microsoft incluyó su propio paquete OpenAPI, que genera la especificación pero sin la interfaz gráfica a la que estábamos acostumbrados; en este artículo vamos a revisar por qué hicieron este cambio, cómo podemos volver a usar Swagger y qué alternativa podemos aprovechar para documentar nuestras APIs.

¿Qué es OpenAPI?#

Antes de abordar el tema de .NET 9 y Swagger, es importante que entendamos qué es OpenAPI y por qué es relevante en este contexto.

OpenAPI es un estándar abierto para documentar APIs REST. En pocas palabras: es un formato (generalmente un JSON o YAML) que nos permite explicar de manera clara y estructurada cómo funciona nuestra API.

Por ejemplo, nos permite documentar:

• Qué endpoints tenemos (/users, /products, etc.)
• Qué parámetros esperan nuestros endpoints
• Qué respuestas devuelven (200, 404, 500…)
• Qué modelos de datos utilizamos

A partir de este formato estándar, diversas herramientas como Swagger UI pueden leer el archivo OpenAPI y generar una interfaz gráfica interactiva que permite a los desarrolladores probar y entender nuestra API de manera sencilla.

Las razones detrás de este cambio#

El principal motivo fue que el proyecto Swashbuckle no cuenta con un mantenimiento tan activo y, además, no ha lanzado una versión oficial para .NET 8. Esto obligaba a Microsoft a depender de librerías externas que no siempre se actualizan al ritmo de los nuevos lanzamientos de .NET.

Por esta razón, decidieron crear Microsoft.AspNetCore.OpenApi, un paquete oficial que genera documentos OpenAPI sin depender de herramientas de terceros. De esta manera, Microsoft puede asegurar lanzamientos más rápidos y confiables que estén alineados con cada nueva versión del framework.

IMPORTANT

No es que Swagger “haya muerto”, simplemente Microsoft dejó de incluirlo por defecto en las plantillas de proyecto.

En el siguiente enlace se puede ver la discusión oficial en GitHub sobre este cambio: GitHub Discussion

Cómo volver a usar Swagger UI en .NET 9#

Swagger UI sigue siendo una de las herramientas más populares y útiles para documentar APIs, y muchos desarrolladores estamos familiarizados con su interfaz intuitiva y funcionalidades. La buena noticia es que podemos seguir utilizándola en .NET 9 sin mayor complicación. Para ello debemos de seguir los siguientes pasos:

1. Instalamos el paquete NuGet:

1
dotnet add package Swashbuckle.AspNetCore
2
dotnet add package Swashbuckle.AspNetCore.Annotations

2. Configuramos Swagger en Program.cs:

1
var builder = WebApplication.CreateBuilder(args);
2

3
// other services...
4

5
// add Swagger service
6
builder.Services.AddSwaggerGen(options =>
7
{
8
    options.SwaggerDoc("v1", new OpenApiInfo()
9
    {
10
        Version = "v1",
11
        Title = "Example API Reference",
12
        Description = "Example API documentation for my Web API",
13
    });
14
    options.EnableAnnotations();
15
});
16

17
var app = builder.Build();
18

19
if (app.Environment.IsDevelopment())
20
{
21
  // enable Swagger middlewares
22
  app.UseSwagger();
23
  app.UseSwaggerUI();
24
}
25

26
// other middlewares...
27

28
app.Run();

3. Usamos los atributos de Swashbuckle.AspNetCore.Annotations para documentar nuestros endpoints:

1
[HttpGet("{id}")]
2
[SwaggerOperation(
3
    Summary = "Get item by ID",
4
    Description = "Retrieves an item by its unique identifier"
5
)]
6
public ActionResult<ItemResponse> GetItem([SwaggerParameter("Item ID")] int id)
7
{
8
    // implementation...
9
}

4. Actualizamos launchSettings.json para abrir Swagger UI automáticamente al iniciar la aplicación (opcional):

1
{
2
  "$schema": "https://json.schemastore.org/launchsettings.json",
3
  "profiles": {
4
    "http": {
5
      "commandName": "Project",
6
      "dotnetRunMessages": true,
7
      "launchBrowser": true,
8
      "launchUrl": "swagger",
9
      "applicationUrl": "http://localhost:5102",
10
      "environmentVariables": {
11
        "ASPNETCORE_ENVIRONMENT": "Development"
12
      }
13
    },
14
    "https": {
15
      "commandName": "Project",
16
      "dotnetRunMessages": true,
17
      "launchBrowser": true,
18
      "launchUrl": "swagger",
19
      "applicationUrl": "https://localhost:7175;http://localhost:5102",
20
      "environmentVariables": {
21
        "ASPNETCORE_ENVIRONMENT": "Development"
22
      }
23
    }
24
  }
25
}

5. Ejecutamos la aplicación y esta navegará automáticamente hacia https://localhost:<puerto>/swagger para ver la interfaz de Swagger UI

Usando Scalar, una gran alternativa a Swagger UI#

Si buscamos algo diferente, una alternativa interesante es Scalar, una herramienta de documentación de APIs que en este caso se complementa muy bien con el nuevo paquete Microsoft.AspNetCore.OpenApi y ofrece una interfaz moderna y amigable. Veamos cómo integrarlo en nuestro proyecto:

1. Instalamos el paquete NuGet:

1
  dotnet add package Scalar.AspNetCore

2. Configuramos Scalar en Program.cs:

1
var builder = WebApplication.CreateBuilder(args);
2

3
// other services...
4

5
// use Microsoft OpenApi service
6
builder.Services.AddOpenApi();
7

8
var app = builder.Build();
9

10
if (app.Environment.IsDevelopment())
11
{
12
  // use OpenAPI endpoint
13
  app.MapOpenApi();
14
  // enable Scalar middleware
15
  app.MapScalarApiReference(options =>
16
  {
17
      options.Title = "Example API Reference";
18
      options.Theme = ScalarTheme.BluePlanet;
19
  });
20
}
21

22
// other middlewares...
23

24
app.Run();

3. Usamos metadatos de OpenAPI para documentar nuestros endpoints:

1
[HttpGet("{id}")]
2
[EndpointSummary("Get item by ID")]
3
[EndpointDescription("Retrieves an item by its unique identifier")]
4
public ActionResult<ItemResponse> GetItem([Description("Item ID")] int id)
5
{
6
    // implementation...
7
}

NOTE

Podemos ver todos los atributos disponibles en la documentación oficial de ASP.NET Core.

4. Actualizamos launchSettings.json para abrir Scalar automáticamente al iniciar la aplicación (opcional):

1
{
2
  "$schema": "https://json.schemastore.org/launchsettings.json",
3
  "profiles": {
4
    "http": {
5
      "commandName": "Project",
6
      "dotnetRunMessages": true,
7
      "launchBrowser": true,
8
      "launchUrl": "scalar",
9
      "applicationUrl": "http://localhost:5102",
10
      "environmentVariables": {
11
        "ASPNETCORE_ENVIRONMENT": "Development"
12
      }
13
    },
14
    "https": {
15
      "commandName": "Project",
16
      "dotnetRunMessages": true,
17
      "launchBrowser": true,
18
      "launchUrl": "scalar",
19
      "applicationUrl": "https://localhost:7175;http://localhost:5102",
20
      "environmentVariables": {
21
        "ASPNETCORE_ENVIRONMENT": "Development"
22
      }
23
    }
24
  }
25
}

5. Ejecutamos la aplicación y esta navegará automáticamente hacia https://localhost:<puerto>/scalar para ver la interfaz de Scalar

Conclusión#

Aunque Swagger UI ya no viene por defecto en los proyectos Web API con .NET 9, aún podemos usarlo fácilmente instalando el paquete Swashbuckle. Alternativamente, podemos explorar nuevas herramientas como Scalar que ofrecen interfaces modernas para documentar nuestras APIs. Lo importante es entender que OpenAPI sigue siendo el estándar para describir nuestras APIs y hay varias opciones para generar documentación interactiva a partir de él.