Documentando APIs ASP.NET Core com Swagger

O desenvolvimento de APIs é cada vez mais comum em projetos de software e é fundamental que elas sejam bem documentadas para serem facilmente compreendidas e utilizadas pelos desenvolvedores. Um dos recursos mais populares para documentação de APIs é o Swagger, que permite a criação de documentação de forma automatizada e interativa.

Neste artigo, mostraremos como utilizar o Swagger em projetos ASP.NET Core para documentar suas APIs de forma eficiente e intuitiva. Vamos começar pela configuração do Swagger, passando pelo uso de anotações para definir os endpoints e parâmetros e finalizando com a exibição da documentação gerada. Ao final deste artigo, você estará apto a implementar o Swagger em seus projetos ASP.NET Core e fornecer uma excelente documentação para suas APIs.

Código-fonte: https://github.com/luisdeol/documenting-swagger

O que é Swagger

Swagger é uma ferramenta para documentação e geração de código para APIs (Application Programming Interface). Ele é utilizado para criar documentação de fácil entendimento para desenvolvedores, incluindo informações sobre como utilizar a API, exemplos de chamadas e modelos de dados esperados.

O Swagger utiliza um arquivo YAML ou JSON chamado “Swagger file” para descrever a estrutura da API. Este arquivo inclui informações sobre os endpoints da API, os métodos HTTP permitidos e os parâmetros de entrada e saída. A partir deste arquivo, o Swagger gera automaticamente a documentação da API em formato HTML, que pode ser facilmente acessada por desenvolvedores. Algo positivo é que não precisamos nos preocupar em escrever esse arquivo, já que é gerado automaticamente ao configurar o Swagger em nossa aplicação.

Logo, o Swagger é uma ferramenta valiosa para equipes de desenvolvimento que trabalham com APIs, pois ajuda a garantir que elas sejam desenvolvidas de maneira consistente e de fácil entendimento.

Configurando o Swagger em uma API ASP.NET Core

Utilizaremos uma aplicação ASP.NET Core versão 7.0. A aplicação começa configurada com o Swagger, mais especificamente na classe Program.cs. Que tal ver como nossa aplicação exibe a documentação inicialmente configurada?

Para isto, basta executar a aplicação, e então navegar para o caminho /swagger. Se estiver utilizando o Visual Studio, provavelmente esta é a página padrão aberta ao executar.

Note que ela contém dados bem interessantes como os Controllers, que dentro de cada um contém os endpoints de nossa API.

Documentação de API com Swagger, sem personalizações

Mas falta algo, concorda? Não temos descrição, modelo de objeto, nem o tipo de retorno.

Que tal adicionarmos alguns detalhes em nossa documentação de API?

Primeiramente, adicione o seguinte código ao seu arquivo de projeto, de extensão .csproj.

Após isso, configurar no arquivo Program.cs, substituindo a seguinte linha:

Linha de código existente no arquivo Program.

Pelo código abaixo, que vai permitir configurar informações como título da documentação, versão, e dados de contato. Também será configurado o carregamento dos dados utilizados para documentar os endpoints do Controller.

Nova configuração do Swagger no arquivo Program

Agora, apenas falta adicionar comentários em formato XML em nossas actions dos Controllers. Vou focar na action que define um endpoint HTTP POST.

Action documentada com dados como resumo, objeto de exemplo, parâmetros, retorno e código de resposta.

Com isso, basta executar novamente a aplicação e teremos o visual a seguir, com mais detalhes adicionados ao nosso endpoint de tipo HTTP POST.

Documentação de API com Swagger

Bem melhor, não acha? Temos agora informações sobre o título da documentação e dados de contato, além de dados de descrição, modelo de objeto, e o código de resposta 201 possível.

Quer alavancar sua carreira como Desenvolvedor(a) .NET?

Além de Desenvolvedor .NET Sênior, eu sou instrutor de mais de 700 alunos e também tenho dezenas de mentorados.

Conheça o Método .NET Direto ao Ponto, minha plataforma com mais de 800 videoaulas, com cursos cobrindo temas relacionados a linguagem C# e Programação Orientada a Objetos, APIs REST com ASP NET Core, Microsserviços com ASP NET Core, HTML, CSS e JavaScript, Desenvolvimento Front-end com Angular, Desenvolvimento Front-end com React, JavaScript Intermediário, TypeScript, Formação Arquitetura de Software, Microsoft Azure, Agile, SQL, e muito mais.

Inclui comunidade de centenas de alunos, suporte por ela, plataforma e e-mail, atualizações regulares e muito mais.

Clique aqui para ter mais informações e garantir sua vaga

Conclusão

Em resumo, o Swagger é uma ferramenta valiosa para documentação e testes de API, e é fácil de implementar em projetos ASP.NET Core. Ele fornece uma interface visual para explorar a estrutura e os recursos da API, além de permitir a geração automática de documentação a partir de nosso código. Isso torna o processo de desenvolvimento e manutenção da API muito mais simples e eficiente. Com o Swagger, os desenvolvedores podem garantir que a API seja fácil de entender e utilizar para outros desenvolvedores e usuários finais.