C# Academy · Lección

Generación de documentos OpenAPI

Produzca especificaciones de API legibles por máquinas.

Generación de documentos OpenAPI es una lección gratuita de C# Academy en CoddyKit. Esta es la lección 3 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de C# Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de C# Academy incluye 4 lecciones en total.

¿Qué es OpenAPI?

OpenAPI es una descripción estándar y legible por máquinas de una API HTTP. A partir de ella puede generar documentación, SDK de cliente y herramientas de prueba.

.NET 9 incluye la generación integrada de documentos de OpenAPI, lo que sustituye la dependencia anterior de Swashbuckle en muchas aplicaciones.

// OpenAPI document = JSON describing paths, schemas, params

El paquete Microsoft.AspNetCore.OpenApi

La compatibilidad integrada se encuentra en Microsoft.AspNetCore.OpenApi. En las plantillas de .NET 9 ya se incluye como referencia.

dotnet add package Microsoft.AspNetCore.OpenApi

AddOpenApi

Registre el generador de documentos con AddOpenApi en la configuración de servicios.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

MapOpenApi

MapOpenApi expone el documento generado en un endpoint. De forma predeterminada, lo sirve en /openapi/v1.json.

var app = builder.Build();

app.MapOpenApi();   // GET /openapi/v1.json

app.Run();

Restringirlo al entorno de desarrollo

Es habitual exponer el documento únicamente durante el desarrollo para evitar revelar la superficie expuesta de la API en producción.

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

Descripción de endpoints

Los metadatos de OpenAPI se enriquecen a partir del código. Use WithSummary, WithDescription y WithTags en los endpoints de Minimal APIs.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .WithSummary("Get a product by id")
   .WithDescription("Returns a single product or 404.")
   .WithTags("Products");

Documentación de respuestas

Declare los tipos de respuesta y los códigos de estado para que el documento los enumere correctamente.

app.MapGet("/products/{id}", (int id) => Results.Ok())
   .Produces<Product>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

Transformadores de documentos

Personalice todo el documento —título, versión y servidores— con un transformador de documentos que se pasa a AddOpenApi.

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API";
        doc.Info.Version = "1.0";
        return Task.CompletedTask;
    });
});

Transformadores de operaciones

Un transformador de operaciones ajusta operaciones individuales; por ejemplo, puede añadir un parámetro de encabezado común a todos los endpoints.

options.AddOperationTransformer((operation, ctx, ct) =>
{
    operation.Responses.TryAdd("500",
        new OpenApiResponse { Description = "Server error" });
    return Task.CompletedTask;
});

Adición de una interfaz de usuario

El generador integrado produce el documento JSON, pero no una interfaz de usuario. Combínelo con un visor como Scalar o Swagger UI.

// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference();  // interactive docs at /scalar/v1

Generación durante la compilación

Puede generar el archivo de OpenAPI durante la compilación, sin ejecutar el servidor, mediante las herramientas de Microsoft.Extensions.ApiDescription.Server; resulta útil para generar clientes en CI.

// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build

Comprobación rápida

Confirme los conceptos básicos de OpenAPI en .NET 9.

Resumen

Ha generado documentos de OpenAPI:

AddOpenApi() registra el generador; MapOpenApi() sirve el JSON.
Enriquezca los endpoints con WithSummary, Produces y etiquetas.
Los transformadores de documentos y de operaciones personalizan el resultado.
Combínelos con Scalar o Swagger UI para obtener una vista interactiva.

Siguiente: documentar API versionadas.

Preguntas frecuentes

¿La lección «Generación de documentos OpenAPI» es gratis?

Sí — el texto completo de «Generación de documentos OpenAPI» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de C# Academy, actualiza a CoddyKit PRO. El curso de C# Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Generación de documentos OpenAPI»?

Produzca especificaciones de API legibles por máquinas. Practicas C# Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar C# Academy?

No se requiere experiencia previa. C# Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 4.

¿Cuánto tiempo toma la lección «Generación de documentos OpenAPI»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de C# Academy?

Sí. Cada lección de C# Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a C# Academy