Inclua Swagger No Seu Projeto! Documentando APIs

Leia, s-u-é-g-u-e-r.

Toda vez que você trabalha com alguma tipo de lógica e quer expor essa lógica para sua aplicação, a forma mais convencional é criando um controller e fazendo com que ele acesse seu método ou função. Se estiver tudo certinho, você conseguirá consumir este endpoint (disponibilizado no seu controller), porém imagine que o projeto comece a crescer, você terá dezenas de endpoint no projeto e terá que fazer uma documentação de cada endpoint, e com certeza seu amigo de projeto não vai documentar ou esquecer de mudar a documentação quando mudar o endpoint e você vai perder um tempo exorbitante no projeto.

E aqui que entra o Swagger, ele é é uma documentação interativa dinâmica de todo projeto, através dele você pode chamar cada um dos seus endpoints e este fornecerá a chamada correta que precisa fazer para que haja uma comunicação com seu controller. Caso seu amiguinho não produza documentação nenhuma daquele novo endpoint que ele disponibilizou, o swagger vai te mostrar o que você precisa enviar e o que você vai receber quando aquele código executar.

Exemplo

Abaixo tem um exemplo de uma chamada em algum endpoint da API que construímos via Swagger. O parâmetro de entrada é o nome e o resultado dessa chamada é aquele objeto no final da imagem marcado de vermelho.

Detalhe, zero documentação para que isso fosse gerado e se você clicar em Try it out, você consegue chamar e ver o resultado da execução.

Isso não é novo e já esta na maioria dos projetos (espero), também espero que você já tenha utilizado, caso contrário abaixo ensino a implantar e já utilizar.

Crie um projeto com Swagger

Aqui é a parte fácil. Você pode criar um projeto Web Application via interface ou rodar via dotnet cli. Para economizar tempo, vamos rodar via CLI.

// Criando a solução
dotnet new sln -n solucao

// Criando o projeto
dotnet new webapi -lang c# -n meu-projeto

// Incluindo o projeto na solucão
dotnet sln add meu-projeto

Criando o projeto utilizando o dotnet cli acima, seu projeto já terá uma estrutura mínima e já estará com o swagger habilitado.

Entenda como funciona

Abrindo o arquivo Startup.cs, você verá duas chamadas do Swagger:

• app.UseSwagger – garante que seu projeto estará habilitado para uso do Swagger;
• app.UseSwaggerUI – esta instrução indica onde está o arquivo de configuração criado pelo UseSwagger.

Visualizando o Swagger

Agora que já entendeu como funciona, execute seu projeto. Com o projeto rodando, basta você verificar a porta que esta em execução (provavelmente a porta 5000) e digitar a URL dessa forma no navegador.

http://localhost:5000/swagger

Se aparecer o swagger, maravilha, use e abuse desse ferramenta, vai ser bem importante para seus projetos.