Documentación de una API mediante Swashbuckle
Swashbuckle es un paquete NuGet que proporciona una manera de generar automáticamente documentación de Swagger para los proyectos de AsP.NET Web API. Swagger es una herramienta que ayuda a los desarrolladores a diseñar, compilar, documentar y consumir diferentes API RESTful. Con Swashbuckle, puede agregar fácilmente documentación de Swagger al proyecto de API web al anotar el código con atributos que describen los puntos de conexión, los parámetros y las respuestas de la API. Después, Swashbuckle usa esta información para generar un archivo JSON de Swagger, que se puede utilizar para generar documentación interactiva de API, SDK de cliente, etc.
Hay tres componentes principales de Swashbuckle:
Swashbuckle.AspNetCore.Swagger: un middleware y modelo de objetos de Swagger para exponer objetos SwaggerDocument como puntos de conexión JSON.
Swashbuckle.AspNetCore.SwaggerGen: un generador de Swagger que compila objetos SwaggerDocument directamente desde las rutas, controladores y modelos. Se suele combinar con el middleware de punto de conexión de Swagger para exponer automáticamente el JSON de Swagger.
Swashbuckle.AspNetCore.SwaggerUI: versión insertada de la herramienta de interfaz de usuario de Swagger. Interpreta el JSON de Swagger para crear una experiencia enriquecida y personalizable para describir la funcionalidad de la API web. Incluye herramientas de ejecución de pruebas integradas para los métodos públicos.
El siguiente comando dotnet add instala el paquete NuGet Swashbuckle:
dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0
Agregar y configurar el middleware de Swagger
Agregue el generador de Swagger a la colección de servicios en Program.cs.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
Nota:
La llamada a AddEndpointsApiExplorer que se muestra en el ejemplo anterior solo es necesaria para las API mínimas.
Habilite el middleware para atender el documento JSON generado y la interfaz de usuario de Swagger, también en Program.cs:
app.UseSwagger();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI();
}
El punto de conexión predeterminado para la interfaz de usuario de Swagger es http:<hostname>:<port>/swagger.
Nota:
SwaggerUI es muy útil en el entorno de desarrollo. Se puede habilitar en producción, pero debe tener en cuenta los requisitos de seguridad de su aplicación específica antes de hacerlo.
Personalización y ampliación de la documentación de Swagger
Swagger proporciona opciones para documentar el modelo de objetos y personalizar la interfaz de usuario. La acción de configuración que se pasa al método AddSwaggerGen puede incluir información adicional a través de la clase OpenApiInfo.
En el ejemplo de código siguiente, se muestra cómo agregar información para mostrarla en la documentación de la API.
// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Fruit API",
Description = "API for managing a list of fruit their stock status.",
TermsOfService = new Uri("https://example.com/terms")
});
});
La interfaz de usuario de Swagger muestra la versión y la información agregada:
Puede agrupar operaciones en su API con la opción .WithTags. También puede agregar un texto descriptivo que describa la operación con la opción .WithSummary. El siguiente código de ejemplo muestra cómo usar .WithTags para agrupar la operación POST en un grupo publicado y un grupo fruta. También agrega a la operación el resumen especificado en la opción.WithSummary.
app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
db.Fruits.Add(fruit);
await db.SaveChangesAsync();
return Results.Created($"/{fruit.Id}", fruit);
})
.Produces<Fruit>(201)
.WithTags("post", "fruits")
.WithSummary("Create a new fruit");
La interfaz de usuario Swagger muestra la agrupación especificada y la descripción resumida.
