.NET 5 + ASP.NET Core + Swagger: descomplicando o versionamento de APIs REST
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:
