Documentación de Swagger con bibliotecas externas

Usar varias bibliotecas para dividir el código para casos futuros es algo bueno. Personalmente me encanta hacerlo, si puedo dividir mi lógica para poder reutilizarla en otros proyectos o partes de los proyectos.

Al menos para mí, es imprescindible dividir los modelos de datos, que incluyen el Entity Framework, para que pueda ser referenciado y utilizado en un Console application, un Blazor application o un API.

Echemos un vistazo a un ejemplo de cómo hago las cosas. Esta es una captura de pantalla de un proyecto que tiene algunas aplicaciones y una biblioteca compartida que tiene todos los modelos.

Este es un ejemplo de una clase que moví del proyecto API con documentación con summary en cada propiedad y clase.

namespace CustomLibrariesDocumentation.Models
{
    /// <summary>
    /// WeatherForecast class
    /// </summary>
    public class WeatherForecast
    {
        /// <summary>
        /// Gets or sets the Date
        /// </summary>
        public DateOnly Date { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureC
        /// </summary>
        public int TemperatureC { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureF
        /// </summary>
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

        /// <summary>
        /// Gets or sets the Summary
        /// </summary>
        public string? Summary { get; set; }
    }
}

Si lo referenciamos al Console application y comenzamos a usar el modelo, podemos ver la documentación, esa es una característica estándar en Visual Studio por lo que funciona bien, como puedes ver aquí:

Pero luego, si lo hacemos referencia a API y vamos a Swagger, no hay documentación resumida.

¿Cómo solucionamos esto?

Primero, tenemos que habilitar los comentarios XML en la biblioteca; para hacer esto, necesita actualizar la configuración del proyecto y habilitar ``:

Esto generará algunos archivos en la carpeta de compilación que terminan con la extensión de archivo xml, como puedes ver aquí:

Ahora que hemos hecho esto, tenemos que agregar algunas cosas en Program.cs, para poder leer esos archivos, esto se debe a que de forma predeterminada solo carga la definición XML del proyecto en el que se encuentra.

Utiliza un método que tenemos dentro del AddSwaggerGen que se llama IncludeXmlComments.

La idea es que si tenemos todos los archivos xml, vamos a forzar la carga en el Swagger.

builder.Services.AddSwaggerGen(s =>
{
    // Comments
    var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

    foreach (string xmlFiles in allXmlFiles)
    {
        s.IncludeXmlComments(xmlFiles);
    }
});

Es sencillo, obtenemos los archivos xml del directorio de compilación y los agregamos con el método IncludeXmlComments.

Ahora cargamos nuevamente el API y comprobamos si podemos ver la documentación.

¡Y puedes ver que podemos ver la documentación!

Espero que te haya ayudado, si tienes alguna pregunta ¡no dudes en contactarme!