.NET 5 + ASP.NET Core + Swagger: descomplicando o versionamento de APIs REST

Renato Groffe
4 min readJul 5, 2021

Conviver com diferentes versões em uma mesma API REST é algo por vezes inevitável, sobretudo quando implementamos integrações com diferentes parceiros em um mesmo projeto. A comercialização de serviços por meio de APIs REST também exemplifica muito bem esta questão, com vários clientes interagindo com diversas versões de um mesmo produto oferecido.

E como facilitar a codificação e o gerenciamento das versões de uma API REST ao trabalharmos com ASP.NET Core?

Muito embora seja impossível escapar da implementação de vários Controllers atrelados a diferentes versões da API em questão, podemos tirar proveito de recursos e até mesmo exemplos do projeto open source ASP.NET API Versioning (incluindo o suporte a Swagger) a fim de descomplicar este processo:

https://github.com/microsoft/aspnet-api-versioning

O ASP.NET API Versioning é uma iniciativa mantida pela própria Microsoft e que já foi abordada recentemente no próprio blog oficial do ASP.NET:

Este projeto inclusive foi uma das alternativas que apresente em uma live recente sobre desenvolvimento Back-End no Canal .NET (acesse este link e assista à gravação no ponto em que abordo o uso do ASP.NET API Versioning):

O exemplo que utilizei também já está disponível no GitHub:

https://github.com/renatogroffe/ASPNETCore5-REST_API-Swagger-Versioning_ContagemAcessos

Para integrar o versionamento da API ao Swagger tomei como base também o seguinte projeto de exemplo, uma criação do time de desenvolvimento do ASP.NET API Versioning:

https://github.com/microsoft/aspnet-api-versioning/tree/master/samples/aspnetcore/SwaggerSample

Na imagem a seguir podemos observar a estrutura deste projeto (uma API REST para contagem de acessos), com 2 Controllers e diferentes implementações da classe ResultadoContador nos diretórios V1 e V2:

A listagem seguinte traz um Controller com as implementações para as versões 1.0 e 1.1 da API REST:

  • O atributo ApiVersion permite indicar quais versões serão mapeadas para Controller, além de especificar eventualmente se alguma destas tem seu uso definido como Deprecated (a ser descontinuado);
  • Além da presença habitual do atributo Route (linha 12), uma segunda utilização permitirá que se inclua na rota o número de versão a ser considerado para a API REST (linha 13 - ao invés de informar o mesmo em uma query string com o parâmetro api-version);
  • O atributo MapToApiVersion (empregado em conjunto com HttpGet) possibilita mapear as requisições para Actions específicas por versão.

E temos a classe ResultadoContador usada por este Controller:

Na próxima listagem temos a implementação do Controller para a versão 2.0 (é possível omitir aqui o uso do atributo MapToApiVersion):

E também sua versão específica do tipo ResultadoContador:

Realizei ainda diversos ajustes na classe Startup:

  • A chamada a AddApiVersioning em ConfigureServices permite indicar uma versão default para a API (o redirecionamento de rotas dispensa com isso o uso do número da versão numa query string ou rota);
  • Já o método AddVersionedApiExplorer efetua a integração do versionamento com a utilização do Swagger;
  • As classes ConfigureSwaggerOptions e SwaggerDefaultValues contam com customizações para integração com o Swagger, tendo sido disponibilizadas no próprio projeto de exemplo do ASP.NET API Versioning que mencionei anteriormente;
  • A chamada ao método UseSwaggerUI em Configure foi adaptada, de maneira que exiba as diferentes versões da API a partir da interface gráfica do Swagger.

Na próxima imagem podemos observar as diferentes versões disponíveis e listadas na interface do Swagger:

Ao acessar a versão 1.0 será destacado que a mesma se encontra como Deprecated:

A seguir temos um teste com a versão 2.0 e a URL http://localhost:5000/Contador?api-version=2.0:

Podemos também informar uma versão como parte da rota de acesso (como a versão 1.0 - http://localhost:5000/v1.0/Contador):

Como a versão 1.1 é a default podemos omiti-la ao definir uma URL de acesso à API REST:

Recomendo fortemente que você assista também ao vídeo do Canal .NET (acessível através deste link) para entender toda a dinâmica envolvendo o uso do ASP.NET API Versioning, contemplando também ajustes adicionei que realizei durante a live.

E para concluir deixo aqui um convite…

Dia 07/07 (quarta) às 21:00 horário de Brasília — teremos mais um evento online e gratuito no canal Canal .NET.

Ao longo desta live demonstrarei em exemplos práticos alguns dos novos recursos do .NET 6, incluindo melhorias em C#, LINQ e ASP.NET Core, o Visual Studio 2022 e o suporte a esta nova versão no Microsoft Azure, Azure DevOps e GitHub Actions!

Para participar faça sua inscrição no link a seguir, a transmissão acontecerá via YouTube:

https://bit.ly/live-dotnet6-novidades-jul-2021

--

--

Renato Groffe

Microsoft Most Valuable Professional (MVP), Multi-Plataform Technical Audience Contributor (MTAC), Software Engineer, Technical Writer and Speaker