Documentación de la API web de ASP.NET Core con Swagger/OpenAPI

Por Christoph Nienaber y Rico Suter

Swagger (OpenAPI) es una especificación independiente del lenguaje que sirve para describir API REST. Permite a los equipos y a los usuarios comprender las capacidades de una API REST sin acceso directo al código fuente. Sus principales objetivos son los siguientes:

• Minimizar la cantidad de trabajo necesaria para conectar los servicios desacoplados.
• Reducir la cantidad de tiempo necesario para documentar un servicio con precisión.

Las dos implementaciones principales de OpenAPI para .NET son Swashbuckle y NSwag, consulte:

• Introducción a Swashbuckle
• Introducción a NSwag

OpenApi en comparación con Swagger

El proyecto de Swagger se donó a la iniciativa OpenAPI en 2015 y desde entonces se conoce como OpenAPI. Ambos nombres se usan indistintamente. Sin embargo, "OpenAPI" hace referencia a la especificación. "Swagger" hace referencia a la familia de productos comerciales y de código abierto de Smartbear que funcionan con la especificación OpenAPI. Los siguientes productos de código abierto, como OpenAPIGenerator, también se encuentran bajo el nombre de la familia de Swagger, a pesar de no ser publicados por Smartbear.

En resumen:

• OpenAPI es una especificación.
• Swagger es una herramienta que usa la especificación OpenAPI. Por ejemplo, OpenAPIGenerator y SwaggerUI.

Especificación de OpenAPI (openapi.json)

La especificación OpenAPI es un documento que describe las capacidades de la API. El documento se basa en XML y anotaciones de atributos dentro de los controladores y modelos. Es la parte principal del flujo OpenAPI y se usa para impulsar herramientas como SwaggerUI. De forma predeterminada, se denomina openapi.json. Este es un ejemplo de especificación de OpenAPI (se ha reducido por motivos de brevedad):

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Interfaz de usuario de Swagger

La interfaz de usuario de OpenAPI es una interfaz de usuario basada en Internet que proporciona información sobre el servicio por medio de la especificación de Swagger generada. Swashbuckle y NSwag incluyen una versión insertada de la interfaz de usuario de Swagger, de modo que se puede hospedar en una aplicación ASP.NET Core realizando una llamada de registro de middleware. La interfaz de usuario web tiene este aspecto:

Todos los métodos de acción públicos aplicados a los controladores se pueden probar desde la interfaz de usuario. Seleccione un nombre de método para expandir la sección. Agregue todos los parámetros necesarios y seleccione Try it out! (¡Pruébelo!).

Nota

La versión de interfaz de usuario de Swagger usada para las capturas de pantalla es la versión 2. Para obtener un ejemplo de la versión 3, vea el ejemplo de Petstore.

Proteger puntos de conexión de interfaz de usuario de Swagger

Llamar MapSwagger().RequireAuthorizationpara proteger los puntos de conexión de la interfaz de usuario de Swagger. En el ejemplo siguiente se protegen los puntos de conexión de Swagger:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

  if (app.Environment.IsDevelopment())
  {
    app.UseSwagger();
    app.UseSwaggerUI();
  }

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

En el código anterior, el punto de conexión /weatherforecast no necesita autorización, pero sí los puntos de conexión de Swagger.

El siguiente Curl pasa un token JWT para probar el punto de conexión de la interfaz de usuario de Swagger:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

Para obtener más información sobre las pruebas con tokens JWT, consulte Generación de tokens con dotnet user-jwts.

Genere un archivo de documentación XML en tiempo de compilación.

Consulte GenerateDocumentationFile para obtener más información.

Pasos siguientes

• Get started with Swashbuckle (Introducción a Swashbuckle)
• Get started with NSwag (Introducción a NSwag)