Documentação Swagger .NET Core com VS Code
Tags: dotnet, csharp, vscode
Published: 2020-07-16 11:57:07

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**.

{% gist https://gist.github.com/juniorporfirio/3de1ba860c4d35c308bf09d44c45025a file=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.

{% gist https://gist.github.com/juniorporfirio/f47002cdc582deeeb1281a892a7ed8a3 file=Startup.cs %}

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.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/vshi9qajcxand7ewvg3e.png)

# 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**.
{% gist https://gist.github.com/juniorporfirio/98eab99c4b9c6f0046ebca223f14f874 file=WeatherForecastController.cs %}

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:
{% gist https://gist.github.com/juniorporfirio/70a5a35933270958a1725b51b84bb5b9 file=SwaggerWebApi.csproj %}

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:
{% gist https://gist.github.com/juniorporfirio/5c23f0ac9894600c5fc4f460b6ef5b25 file=Startup.cs %}

Agora sim, ao acessar o endpoint da documentação do Swagger é visualizado os comentários informados nas Actions do Projeto.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/96g1qgujg0j2lii53inc.png)

# 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

https://docs.microsoft.com/pt-br/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio

{% github https://github.com/juniorporfirio/Swagger-Example %}