Sempre que necessitamos consumir uma API RESTFul a primeira coisa que nos vem a cabeça ?
Será que existe uma documentação.
Consumir APIs RESTFul sem uma documentação é como um cego sem seu cão guia, ficamos literalmente perdidos, não desejamos passar por essa situação e também sejamos responsáveis de sempre pensar nos consumidores das APIs RESTFul que desenvolvemos, incluindo uma documentação.
Para isto apresento para vocês o Swagger, que resolve esse problema de documentação de APIs de forma muito simples e rápida.
O Swagger é um package Open Source desenvolvedo em meados de 2010 com o objetivo de facilitar a documentação de APIs RESTFul,com ela será possível:
- visualizar a documentação em uma página dos recursos.
- testar todos os recursos nos respectivos verbos(GET,POST, PUT, PATCH, DELETE)
- configurar autorização destes recursos de forma visual.
- testar todos os recursos e seus respectivos verbos sem a necessidade do uso do famoso POSTMAN :).
Criando um Projeto
Para isto vamos criar um novo projeto no Visual Studio Code utilizando o seguinte comando no terminal.
dotnet new sln -o “SwaggerExample”
Criar um projeto WebApi
dotnet new webapi -o “SwaggerWebApi”
Agora vamos associar o projeto Web Api a Soluction com o seguinte comando.
dotnet sln add src/SwaggerWebApi/SwaggerWebApi.csproj
Instalando o Package
Vamos instalar o package Swashbuckle no projeto WebApi.
dotnet add package Swashbuckle.AspNetCore
Configurando o Swagger
Após a instalação do package Swashbuckle, vamos configurar o Swagger para isto, precisamos abrir o arquivo Startup.cs.
Como vocês podem perceber é possivel informar várias informações para sua documentação, como por exemplo, a versão de sua Api, titulo, descrição, e os dados de contato, tudo isto será exibido na página de documentação de sua aplicação.
Agora iremos incluir as configurações no mesmo arquivo Startup.cs no método Configure, nela será possível realizar as configurações de endpoint da documentação.
Com apenas essas simples configurações já será possível acessar a página de documentação Swagger, para isto, basta acessar “/swagger” na sua aplicação.
Incluindo comentários de código no Swagger
Como vocês podem perceber, podemos melhorar ainda mais a nossa documentação aproveitando os comentários da aplicação fazendo o uso do summary, e exibindo na nossa página do Swagger.
Agora precisamos configurar nosso projeto para gerar essa documentação durante o build, para isto, vamos editar o arquivo SwaggerWebApi.csproj, incluindo a configuração GenerateDocumentationFile, conforme arquivo abaixo:
Para que o Swagger possa entender as documentações geradas em um arquivo durante o build, precisamos informar ao Swagger este arquivo, conforme o exemplo abaixo:
Agora sim, ao acessar o endpoint da documentação do Swagger é visualizado os comentários informados nas Actions do Projeto.
Conclusão
Como podemos perceber é bem simples a configuração do Swagger e nos dá o poder de utilizar junto com os comentários da aplicação .NET, distribuir essa documentação através de um endpoint padrão, dando a possibilidade de chamar os recursos através da página.
Sempre que necessitar criar uma aplicação Api RESTFul, a configuração do Swagger se torna obrigatória.
Referências
juniorporfirio
/
Swagger-Example
Example who configure Swagger using Visual Studio Code
Swagger-Example
Example who configure Swagger using Visual Studio Code
Top comments (0)