Documentação viva com Swagger e .NET Core

Olá, pessoal!

Hoje vamos tocar em um assunto que muita gente não gosta, mas que é muito importante: documentação!

Em um mundo integrado, onde os sistemas se comunicam com muita frequência, é difícil não precisarmos de uma documentação. Eu sei, talvez você, como dev, não goste de ler isso – mas é verdade.

Além disso, a outra opção é você ter que conversar por telefone, e-mail ou sinal de fumaça com cada terceiro que fará a integração.

Se você não gostou da segunda opção, é porque ela é bem ruim mesmo! Além de ser chato conversar sobre endpoints e esclarecer essas coisas por telefone, também não é um modelo exatamente escalável.

O ideal é que sua aplicação tenha uma documentação própria e que todos os envolvidos em uma integração pudessem obter todas as informações necessárias através dela.

• Certo, vamos escrever um doc?

Não. Por favor, não.

Não que escrever docs seja a pior coisa do mundo – spoiler: não são. Mas uma documentação deste tipo tende a ficar desatualizada com o tempo e uma documentação desatualizada serve para vários nadas.

A documentação precisa ser viva, ou seja: software atualizou? Documentação precisa atualizar também!

Existem diversas maneiras diferentes para criarmos uma documentação viva. Uma delas é o Swagger.

Swagger

O Swagger é um framework open-source para documentação de APIs. Ele descreve os recursos disponíveis, separando por controllers e actions, mostrando parâmetros de entrada, retornos, códigos HTTP, autenticação e praticamente todas as informações de sua API.

Existem várias ferramentas para auxiliar neste processo de criar a documentação utilizando Swagger, você pode encontrá-las pela internet aos montes.

O que vamos fazer aqui é um pouco diferente, vamos configurar nossa aplicação para que ela mesma gere a documentação com nossos endpoints!

Vamos começar criando nossa aplicação .NET Core através do Visual Studio. Na prática, se você criar a aplicação por linha de comando não verá nenhuma diferença, então sinta-se à vontade!

Com isso, sua aplicação base é criada, contendo apenas o ValueController. Agora vamos preparar a aplicação para integração com o Swagger!

O primeiro passo é instalarmos o pacote SwashBuckle em nossa aplicação:

PM> Install-Package Swashbuckle.AspNetCore

Com os pacotes instalados já é possível configurar a documentação. Para isso, vamos para a classe Startup, responsável pela configuração dos serviços da aplicação.

Faremos a alteração no método ConfigureServices. Por padrão, este método contará apenas com uma instrução de: services.AddMvc();. Nossa modificação acontecerá após essa instrução, conforme código:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddSwaggerGen(options =>
        options.SwaggerDoc("beta",
            new Info
            {
                Title = "Exemplo de documentação",
                Version = "beta",
                Description = "Projeto ASP.Net Core",

                Contact = new Contact
                {
                    Name = "Gabriel Schade",
                    Url = "https://gabrielschade.github.io"
                }
            })
    );
}

Note que várias dessas informações você deverá preencher conforme o projeto, inclusive a versão (que informei como beta).

Após isso, incluiremos algumas instruções no método Configure. Essas configurações criam o endpoint para visualizarmos a documentação.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseMvc();
    app.UseSwagger();
    app.UseSwaggerUI(setup =>
    {
        setup.RoutePrefix = "swagger";
        setup.SwaggerEndpoint("/swagger/beta/swagger.json", "Exemplo de documentação");
    });
}

Só com essas alterações já conseguimos visualizar a página de documentação online! Para isso, precisamos acessar a página “/swagger“, conforme configurado anteriormente:

A página gerada é totalmente interativa, podendo, inclusive, realizar chamadas à sua API, o que pode ser bastante útil para os consumidores das APIs.

No entanto, ainda não configuramos um detalhe bastante importante, veja só como o endpoint Values/{id} está sendo visualizado na documentação:

Apesar da action estar listada, não conseguimos ver uma descrição humana da action ou de seus parâmetros. Felizmente podemos fazer isso através dos comentários do próprio código!

/// <summary>
/// Método para obter todos os valores disponíveis
/// </summary>
/// <returns>
/// Retorna todos os valores
/// </returns>
[HttpGet]
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

/// <summary>
/// Método para obter um valor específico
/// </summary>
/// <param name="id">Id do valor que será obtido</param>
/// <returns>
/// Retorna o valor de acordo com o Id informado
/// </returns>
[HttpGet("{id}")]
public string Get(int id)
{
    return "value";
}

/// <summary>
/// Método para publicar um valor de acordo com o parâmetro
/// </summary>
/// <param name="value">
/// Valor que deve ser publicado
/// </param>
[HttpPost]
public void Post([FromBody]string value)
{}

Note que inclui descrições relativamente genéricas. Claro que isso porque essa API é apenas um exemplo. Em aplicações reais é importante descrever todas as características principais para comunicação com sua API, sem exceção.

Agora que já criamos os comentários, precisamos informar para o Swagger a forma de carregá-los. A primeira coisa a fazer é indicar em seu projeto que você está gerando o arquivo XML com os comentários. Para fazer isso, acesse as propriedades de seu projeto e marque a opção “XML Documentation file“, conforme a imagem:

Por fim, vamos voltar ao método ConfigureServices e incluir as instruções na chamada ao método AddSwaggerGen, conforme o código abaixo:

services.AddSwaggerGen(options =>
{
    string caminhoAplicacao = PlatformServices.Default.Application.ApplicationBasePath;
    string nomeAplicacao = PlatformServices.Default.Application.ApplicationName;
    string caminhoDocumentacao = Path.Combine(caminhoAplicacao, $"{ nomeAplicacao}.xml");
    options.IncludeXmlComments(caminhoDocumentacao);

    options.SwaggerDoc("beta",
        new Info
        {
            Title = "Exemplo de documentação",
            Version = "beta",
            Description = "Projeto ASP.Net Core",

            Contact = new Contact
            {
                Name = "Gabriel Schade",
                Url = "https://gabrielschade.github.io"
            }
        });
});

Note que estou utilizando o caminho padrão para a documentação XML. Caso você tenha escolhido outro caminho, é necessário incluí-lo aqui também.

Agora, sim, ao acessar a página de documentação você verá suas actions e parâmetros comentados!

O mais legal é que o conceito de documentação viva realmente acontece aqui. Vamos fazer o teste criando um novo Controller. Esse controlador será responsável pelo recurso de clientes e teremos apenas um método: ObterId.

Esse método receberá o CPF do cliente e retornará um identificador fictício, confira:

[Route("api/Cliente")]
public class ClienteController : Controller
{
    /// <summary>
    /// Método para obter o Id do cliente por CPF
    /// </summary>
    /// <returns>
    /// Retorna o Id do cliente
    /// </returns>
    [HttpGet]
    public Guid ObterId(string CPF)
        => Guid.NewGuid();
}

É só criamos um controller normalmente, correto? Correto! E mesmo assim, ele já estará disponível na documentação, conforme  a imagem abaixo:

Já pode inclusive testar seu método! Legal, né?

Você pode encontrar a aplicação de exemplo com o Swagger configurado no meu GitHub. O que você achou deste artigo?

Me conte nos comentários.

Até mais!