Documentando APIs em Asp.Net MVC com Swagger

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.

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

Criando novo 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).

Selecionando um tipo de projeto

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.

Definindo a arquitetura

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

Estrutura final

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.

Abrindo o nuget manager console

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

Swagger sendo referenciado 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.

Swagger em funcionamento

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:

Propriedades do projeto

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

Configuração para gerar o XML documents

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

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
Resultado da tag <remarks>
  • <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
Resultado da tag <param>
  • [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
Resultado da anotação [Required]

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.

Bachelor in Computer Science, MBA in Software Architecture and .NET Developer.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store