Documentando APIs em Asp.Net MVC com Swagger

4 min readMay 24, 2018

O Swagger é uma especificação independente de linguagem para descrever APIs REST. Neste conceito, é proposto esboçar como instalar e utilizar o Swagger em aplicações e Asp.Net MVC.

Criação do projeto

Abra o visual studio, vá em Arquivo, selecione a opção Novo e clique em Projeto.

Feito isso, será apresentado uma tela contendo todas as tecnologias disponíveis no visual studio. Selecione o projeto ASP.NET Web Application (.Net Framework).

Após escolher o tipo de tecnologia, é solicitado um tipo de definição da arquitetura da aplicação. Seleciona-se o tipo Web API, onde será gerado modelos para abranger os conceitos de MVC e API.

Ao término, será gerado a seguinte estrutura do projeto.

Instalação do Swagger

Para começar a utilizar o swagger no projeto, tem-se que adicioná-lo como dependência do projeto, instalando o pacote Swashbuckle. Para isso, utiliza-se o Nuget Manager Console.

E insere-se o seguinte comando: Install-Package Swashbuckle
Com isso, será adicionado uma referência do pacote no projeto.

Neste momento, o swagger já está apto para ser utilizado, onde executa-se o projeto e coloca-se o sufixo “/swagger” na url.

Configuração do Swagger

Após instalação do pacote, será criado um arquivo em App_Start/SwaggerConfig.cs. Neste arquivo pode-se realizar algumas configurações, como, por exemplo, habilitar que o Swagger utilize a documentação gerada pelo XML documents. E, para isso tem-se que ir nas propriedades do projeto:

E, selecionar a seção Build e marcar a opção XML documentation file.

Observa-se que será gerada uma string “bin\Swagger.xml”, é necessário copiá-la para inseri-la no seguinte código na classe SwaggerConfig.cs:

Código de configuração do Swagger

Demais configurações

c.IgnoreObsoleteActions() — ignora os controllers que não estão realizando nenhum tipo de ação dentro do projeto;
c.IgnoreObsoleteProperties() — ignora as propriedades não utilizadas no código;
c.ResolveConflictingActions() — quando há mais de uma controller com a mesma rota, com isso é recuperada apenas a primeira (não obrigatoriamente);
c.DocumentTitle() — dar um título há página do Swagger no navegador;
c.DocumentExpansion() — definir se os controllers no Swagger irão aparecer expandidos ou não.

Documentando métodos

Através do XML documents, consegue-se documentar mais detalhadamente a controller. A seguir, esboça-se algumas maneiras de realizar isso.

<summary> — descrever o método ou tipo

Resultado da tag <summary>

<remarks> — adicionar mais informações ao método ou tipo

<remarks> — utilizado também para apresentar algum exemplo do modelo de entrada

Resultado da tag <remarks> para exemplificar modelo

<param name=”name”> — descreve os parâmetros de entrada

[SwaggerResponse] e <response> — descrições dos valores retornados
Consegue-se fazer a documentação do retorno com apenas uma das opções, a diferença é que com a tag insere-se apenas uma descrição e o código da mesma e com a anotação consegue-se inserir, também, um modelo de retorno

Resultado da tag <response> e da anotação [SwaggerResponse]

<summary> na propriedade — descrição da propriedade

Resultado da tag <summary> nas propriedades

[Required] — Obrigatoriedade de informar um valor a uma propriedade

Conclusão

Nota-se que o grau de complexidade para implantar o Swagger não é alto, em poucos passos consegue-se documentar uma API. Além disso, pode-se utilizar o XML documents para descrever detalhadamente o método/serviço.