Swagger Extensions

La clase SwaggerExtensions proporciona métodos de extensión para configurar y habilitar Swagger en aplicaciones ASP.NET Core, simplificando el proceso de documentación de APIs REST. Su objetivo principal es facilitar la configuración de Swagger, incluyendo la definición de información general de la API, la configuración de la autenticación y la habilitación de la interfaz de usuario de Swagger UI.

using CodeDesignPlus.Net.Core.Abstractions.Options;
using CodeDesignPlus.Net.Core.Exceptions;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;


namespace CodeDesignPlus.Net.Microservice.Commons.EntryPoints.Rest.Swagger;

/// <summary>
/// Extensions for configuring Swagger in the service container.
/// </summary>
public static class SwaggerExtensions
{
    /// <summary>
    /// Adds and configures Swagger in the service container.
    /// </summary>
    /// <typeparam name="TProgram">The type of the program class.</typeparam>
    /// <param name="services">The service container.</param>
    /// <param name="configuration">The configuration settings.</param>
    /// <returns>The service container with Swagger configured.</returns>
    public static IServiceCollection AddCoreSwagger<TProgram>(this IServiceCollection services, IConfiguration configuration) where TProgram : class
    {
        ArgumentNullException.ThrowIfNull(services);
        ArgumentNullException.ThrowIfNull(configuration);

        var section = configuration.GetSection(CoreOptions.Section);

        if (!section.Exists())
            throw new CoreException($"The section {CoreOptions.Section} is required.");

        var coreOptions = section.Get<CoreOptions>();

        // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
        var info = new OpenApiInfo()
        {
            Title = coreOptions!.AppName,
            Version = coreOptions!.Version,
            Description = coreOptions!.Description,
            Contact = new OpenApiContact()
            {
                Name = coreOptions!.Contact.Name,
                Email = coreOptions!.Contact.Email,
            }
        };

        services.AddSwaggerGen(x =>
        {
            x.SwaggerDoc(coreOptions.Version, info);

            var xmlFile = $"{typeof(TProgram).Assembly.GetName().Name}.xml";

            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);

            x.IncludeXmlComments(xmlPath);

            x.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
            {
                In = ParameterLocation.Header,
                Description = "Please enter a valid token",
                Name = "Authorization",
                Type = SecuritySchemeType.Http,
                BearerFormat = "JWT",
                Scheme = "Bearer"
            });

            x.AddSecurityRequirement(new OpenApiSecurityRequirement
            {
                {
                    new OpenApiSecurityScheme
                    {
                        Reference = new OpenApiReference
                        {
                            Type=ReferenceType.SecurityScheme,
                            Id="Bearer"
                        }
                    },
                    Array.Empty<string>()
                }
            });
        });

        return services;
    }

    /// <summary>
    /// Configures the application to use Swagger.
    /// </summary>
    /// <param name="app">The application builder.</param>
    /// <returns>The application builder with Swagger configured.</returns>
    public static IApplicationBuilder UseCoreSwagger(this IApplicationBuilder app)
    {
        ArgumentNullException.ThrowIfNull(app);

        var options = app.ApplicationServices.GetRequiredService<IOptions<CoreOptions>>().Value;

        app.UseSwagger();

        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", $"{options.AppName} {options.Version}");
        });

        return app;
    }
}

Dependencias y Requisitos Previos

Microsoft.Extensions.DependencyInjection: Necesario para la interfaz IServiceCollection y el registro de servicios en el contenedor de inyección de dependencias.
Microsoft.Extensions.Configuration: Necesario para la interfaz IConfiguration y la lectura de la configuración de la aplicación.
Microsoft.AspNetCore.Builder: Necesario para la interfaz IApplicationBuilder y el registro de middleware.
Swashbuckle.AspNetCore: Necesario para la funcionalidad de Swagger/OpenAPI en ASP.NET Core.
CodeDesignPlus.Net.Core.Abstractions: Necesario para la interfaz CoreOptions y la configuración de la API.
CodeDesignPlus.Net.Core.Exceptions: Necesario para la excepción CoreException.

Escenarios de uso

Estos métodos de extensión son particularmente útiles en aplicaciones que:

Implementan APIs REST.
Desean generar documentación interactiva para sus APIs usando Swagger.
Necesitan configurar la autenticación con JWT (JSON Web Tokens) en Swagger.
Requieren una configuración sencilla y consistente de Swagger en su aplicación.
Quieren incluir comentarios XML en la documentación de la API.

Beneficios

Configuración simplificada: Reduce la cantidad de código necesario para configurar Swagger en aplicaciones ASP.NET Core.
Configuración centralizada: Permite centralizar la configuración de Swagger utilizando opciones de configuración.
Soporte de Autenticación JWT: Configura automáticamente la autenticación JWT en Swagger.
Integración de comentarios XML: Permite incluir los comentarios XML de la documentación del código en la documentación de Swagger.
Consistencia: Garantiza una configuración consistente de Swagger en toda la aplicación.

Ejemplo Práctico

Para usar estos métodos de extensión en tu aplicación, debes agregarlos al IServiceCollection en el método ConfigureServices y al IApplicationBuilder en el método Configure o MapEndpoints de tu clase Program.cs.

// En tu archivo Program.cs
using CodeDesignPlus.Net.Microservice.Commons.EntryPoints.Rest.Swagger;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;

var builder = WebApplication.CreateBuilder(args);

// Agregar servicios necesarios para ASP.NET Core
builder.Services.AddControllers();

// Agrega la configuración de Swagger utilizando AddCoreSwagger
builder.Services.AddCoreSwagger<Program>(builder.Configuration);


var app = builder.Build();

// Habilitar Swagger y SwaggerUI utilizando UseCoreSwagger
app.UseCoreSwagger();
app.UseRouting();
app.MapControllers();


app.Run();

Es importante que definas la sección Core configuracion en el appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Core": {
    "Business": "CodeDesignPlus",
    "AppName": "sample-rest",
    "Version": "v1",
    "Description": "Sample of CodeDesignPlus.Net.Core",
    "Contact": {
      "Name": "CodeDesignPlus",
      "Email": "custom@outlook.com"
    }
  }
}

Métodos de extensión

La clase SwaggerExtensions proporciona dos métodos de extensión para configurar y habilitar Swagger en aplicaciones ASP.NET Core:

AddCoreSwagger

Type: public static IServiceCollection AddCoreSwagger<TProgram>(this IServiceCollection services, IConfiguration configuration) where TProgram : class

El método de extensión AddCoreSwagger se encarga de configurar Swagger en la aplicación. Durante su ejecución, registra todos los servicios necesarios y ajusta múltiples aspectos críticos. Primero, extrae la información de la API, como el título, la versión, la descripción y los detalles de contacto, directamente desde la configuración proporcionada. Además, integra la documentación de comentarios XML, permitiendo una mayor claridad y detalle en la documentación generada automáticamente. Finalmente, configura la autenticación JWT, asegurando que las comunicaciones y operaciones dentro de la API sean seguras y estén debidamente autenticadas.

Parámetros:
- services: La instancia de IServiceCollection a la cual se agregarán los servicios de Swagger.
- configuration: La instancia de IConfiguration que contiene la configuración de la aplicación.
- TProgram: El tipo de la clase program de tu proyecto, esta se utiliza para obtener el nombre del Assembly y la ruta al archivo XML.
Tipo de retorno:
- IServiceCollection: La misma instancia de IServiceCollection para permitir el encadenamiento de llamadas a métodos.
Excepciones:
- ArgumentNullException: Se lanza si alguno de los parametros services o configuration son nulos.
- CoreException: Se lanza si no se encuentra la sección “Core” en la configuración de la aplicación.

Ejemplo de Código:

// Dentro de ConfigureServices en Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    // Configura Swagger
    services.AddCoreSwagger<Program>(Configuration);
}

UseCoreSwagger(args…)

Type: public static IApplicationBuilder UseCoreSwagger(this IApplicationBuilder app)

Este método de extensión habilita el middleware de Swagger en el pipeline de la aplicación, incluyendo la interfaz de usuario de Swagger UI. Configura el endpoint de Swagger para que utilice la configuración de la API.

Parámetros:
- app: La instancia de IApplicationBuilder a la cual se agregarán los middlewares de Swagger.
Tipo de retorno:
- IApplicationBuilder: La misma instancia de IApplicationBuilder para permitir el encadenamiento de llamadas a métodos.
Excepciones:
- ArgumentNullException: Se lanza si la instancia de app es nula.