Documentação de APIs com Swagger no ASP.Net Core
Não basta apenas desenvolver nossas aplicações e largar na mão dos times que farão uso delas. Uma boa documentação é um dos quesitos chave para o sucesso de todo sistema hoje em dia, ainda mais em um mundo de APIs que vivemos hoje, onde existem cada vez mais integrações entre aplicações e serviços.
Imagina você ter que entrar em contato com o desenvolvedor de determinada API para saber quais endpoints você precisa usar, e quais são os parâmetros necessários para a correta integração com seu sistema. Tanto você, quanto ele ficarão loucos com as trocas de e-mails e telefonemas. Você também não precisa escrever um documento que detalhe o funcionamento de sua API no Word. Esqueça isso!
Hoje vamos ver como criar uma documentação de API efetiva com o Swagger.
Não deixe de conferir um dos meus projetos de exemplo, onde eu faço uso do Swagger, e que está disponível em meu Github.
O que é o Swagger?
O Swagger é um framework open source que ajuda os desenvolvedores no desenho, especificação e documentação de suas APIs. Ele segue a iniciativa Open API que busca a padronização de APIs REST. Essa especificação basicamente descreve os recursos de suas APIs, como endpoints, parâmetros de entrada, objetos de retorno, códigos HTTP, métodos de autenticação, entre outros.
O Swagger possui algumas ferramentas que nos auxiliam em todo o processo de desenvolvimento de nossas APIs, entre elas:
- Swagger Editor → editor online para criar especificações Open API;
- Swagger UI → renderiza especificações Open API em uma interface interativa;
- Swagger CodeGen → gera templates de código a partir de uma especificação Open API.
Configurando o Swagger no ASP.Net Core
Não é necessário criar um arquivo de especificação do Swagger ao utilizar o ASP.Net, podemos gerar a especificação em tempo de execução de forma automática usando a biblioteca Swashbuckle, que conta com versões para ASP.Net (full framework) e ASP.Net Core.
Primeiramente você deve instalar o pacote nuget Swashbuckle.AspNetCore em seu projeto de API.
dotnet add package Swashbuckle.AspNetCore --version 2.5.0
Em seguida, no arquivo Startup.cs do seu projeto será necessário adicionar a configuração necessária para a geração da especificação do Swagger. Isso deve ser feito no método ConfigureServices.
Com isso você já pode rodar sua API e acessar a documentação através do endpoint /swagger. Se você quiser modificar essa rota, basta alterar a propriedade RoutePrefix da configuração ao chamar o método UseSwaggerUI.
Perceba que você pode fazer as chamadas para os recursos de sua API diretamente pela interface do Swagger. Informe os parâmetros necessários e clique no botão Try it out!.
Caso sua API necessite de autenticação para ser acessada, você pode configurar o schema de autenticação usando o método AddSecurityDefinition. No meu caso estou usando ApiKeyScheme, que representa autenticação baseada em token. Para conhecer outros schemas de autenticação do Swagger recomendo a leitura da documentação.
Com isso, o botão Authorize será exibido no cabeçalho da interface do Swagger.
Ao clicar nele será exibida uma janela onde você deve inserir seu token de acesso, no meu caso estou utilizando schema de autenticação Bearer com JWT.
Você também pode usar os comentários de documentação XML (summary) do .Net e deixar sua documentação do Swagger mais rica. Para isso use o método IncludeXmlComments informando o path onde está o arquivo gerado com os comentários.
Para ativar a geração do arquivo de comentários XML, vá nas propriedades do seu projeto de API, clique na guia Build, e em seguida marque a opção “XML documentation file”, deixando o path padrão.
Durante o build de sua aplicação o arquivo de documentação XML será gerado no local especificado e com isso sua documentação do Swagger irá exibir essas mesmas informações.
Conclusão
Como vimos, com a simples adição do Swagger em nossa aplicação, qualquer consumidor conseguirá de forma efetiva usar nossa API.
Além dos recursos descritos nesse artigo, você também pode criar filtros de execução do Swagger, onde por exemplo, você pode omitir determinadas propriedades de modelos da documentação, exibir os endpoints em caixa baixa.
Caso você use versionamento em suas APIs será necessário fazer a configuração no Swagger, mas deixarei para explicar isso em outro artigo.
Espero que tenham gostado!
Se ficou qualquer dúvida ou tenham críticas e sugestões, não deixem de entrar em contato.
Abraços!