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.

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:

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
  • <remarks> — adicionar mais informações ao método ou tipo
  • <remarks> — utilizado também para apresentar algum exemplo do modelo de entrada
  • <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
  • <summary> na propriedade — descrição da propriedade
  • [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.

Referências

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

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