Documentação do Swagger com bibliotecas externas

Usar várias bibliotecas para dividir seu código para casos futuros é uma coisa boa. Pessoalmente adoro fazer isso, se consigo dividir minha lógica para que ela possa ser reutilizada em outros projetos ou partes dos projetos.

Para mim, pelo menos, é obrigatório dividir os modelos de dados, o que inclui o Entity Framework, para que possa ser referenciado e usado em um Console application, um Blazor application ou um API.

Vamos dar uma olhada em um exemplo de como faço as coisas, este é um screenshot de um projeto que possui alguns aplicativos e uma biblioteca compartilhada que possui todos os modelos.

Este é um exemplo de classe que movi do projeto API com documentação com summary em cada propriedade e classe.

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; }
    }
}

Se fizermos referência ao Console application e começarmos a usar o modelo, podemos ver a documentação, que é um recurso padrão no Visual Studio, então funciona bem, como você pode ver aqui:

Mas então, se fizermos referência ao API e formos para Swagger, não haverá documentação resumida.

Como podemos consertar isso?

Primeiro, temos que habilitar os comentários XML na biblioteca, para fazer isso, é necessário atualizar as configurações do projeto e habilitar ``:

Isso irá gerar alguns arquivos na pasta build que terminam com a extensão de arquivo xml, como você pode ver aqui:

Agora que fizemos isso, temos que adicionar algumas coisas no Program.cs, para podermos ler esses arquivos, isso porque por padrão ele carrega apenas a definição XML do projeto em que está.

Ele usa um método que temos dentro do AddSwaggerGen que se chama IncludeXmlComments.

A ideia é que se tivermos todos os arquivos xml, forçaremos o carregamento deles no Swagger.

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

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

É direto, pegamos os arquivos xml do diretório de construção e os adicionamos com o método IncludeXmlComments.

Agora carregamos novamente o API e verificamos se conseguimos ver a documentação.

E você pode ver que podemos ver a documentação!

Espero que tenha ajudado você, qualquer dúvida não hesite em entrar em contato comigo!