.NET + Azure Functions: habilitando o suporte a Swagger com HTTP Trigger
Relativamente recente e ainda com versões em Preview, o time da Microsoft responsável pelas Azure Functions disponibilizou 2 packages NuGet que tornam possível habilitar o uso do Swagger/Open API com HTTP Trigger:
- Microsoft.Azure.WebJobs.Extensions.OpenApi, para implementações baseadas em Azure Functions v3 + .NET Core 3.1;
- Microsoft.Azure.Functions.Worker.Extensions.OpenApi, alternativa para a construção de aplicações que façam uso de Azure Functions v3 + .NET 5.
Trata-se de uma capacidade muito aguardada, sem sombra de dúvidas, entre Desenvolvedores que optam pela implementação de projetos serverless utilizando .NET e Azure Functions.
Em uma live recente no Canal .NET com meu amigo Ewerton Rodrigues Jordão abordamos inclusive esta novidade. A gravação está disponível no YouTube e pode ser assistida gratuitamente:
Os exemplos utilizados na live fora disponibilizados no meu GitHub:
.NET Core 3.1 + Azure Functions 3.x + HTTP Trigger + Swagger/Open API + Conversor de Temperaturas
A intenção deste post é trazer um guia rápido sobre como configurar o uso de Swagger/Open API com Azure Functions, considerando para isto projetos baseados em .NET Core 3.1 e .NET 5.
Nas diversas implementações que incluí neste artigo utilizei como referência os exemplos disponibilizados pelo time do Azure Functions no GitHub:
Azure Functions Sample Apps | GitHub
E aproveito este espaço para um convite…
Nesta próxima quarta 08/09 — partir das 21:00 — horário de Brasília — teremos mais um evento ONLINE e GRATUITO no canal Coding Night.
Desta vez um bate-papo descontraído discutindo o dia a dia do desenvolvimento Back-End: APIs REST, Serverless, dicas, boas práticas, questões de segurança, problemas e dificuldades comuns…
Segue o link para inscrições, a transmissão acontecerá no YouTube:
Configurando um projeto baseado em .NET Core 3.1
O projeto descrito nesta seção foi disponibilizado como um repositório no GitHub e pode ser acessado através deste link.
Além de Microsoft.Azure.WebJobs.Extensions.OpenApi, foi também adicionado neste exemplo o package Microsoft.Azure.Functions.Extensions a fim de possibilitar a utilização de injeção de dependências com .NET Core 3.1 e Azure Functions:
Precisaremos então implementar a classe OpenApiConfigurationOptions, a qual conterá informações gerais sobre a Function App/API que estamos implementando e deriva do tipo DefaultOpenApiConfigurationOptions:
E a classe AppSettings, a qual herdará do tipo OpenApiAppSettingsBase:
Este projeto também possuirá uma classe Startup, criada com o objetivo de ativar o mecanismo de injeção de dependências requerido para uso do tipo AppSettings:
E chegamos à implementação da Function ConversorFahrenheit. A utilização dos atributos OpenApiOperation, OpenApiSecurity, OpenApiParameter e OpenApiResponseWithBody permitirá configurar o Swagger para o endpoint representado por esta Azure Function:
Podemos observar esta aplicação na imagem a seguir em execução a partir do Visual Studio Code, incluindo os endpoints do Swagger disponibilizados também como Functions:
E a própria interface gráfica do Swagger acessada via browser:
Configurando um projeto baseado em .NET 5
O projeto aqui detalhado é uma variação da aplicação apresentada na seção anterior, desta vez fazendo uso de .NET 5. Também disponibilizei esta Function App no GitHub através deste link.
Diferentemente do projeto anterior, foi adicionado a esta Function App apenas o package Microsoft.Azure.Functions.Worker.Extensions.OpenApi:
Para as configurações da API representada pela Azure Function de conversão de temperaturas foi criada apenas a classe OpenApiConfigurationOptions (que será detectada automaticamente ao se configurar o Swagger):
Os ajustes ativando o Swagger/Open API acontecerão na classe Program:
- Na chamada a ConfigureFunctionsWorkerDefaults foi configurada a serialização via Newtonsoft (linha 14);
- É necessário ainda acionar o método ConfigureOpenApi (linha 15).
Exceto pelas diferenças entre o desenvolvimento em .NET Core 3.1 e .NET 5, a Function ConversorFahrenheit deste novo exemplo também foi configurada com os atributos OpenApiOperation, OpenApiSecurity, OpenApiParameter e OpenApiResponseWithBody a fim de que ocorra a integração com o Swagger/Open API:
Temos na próxima imagem esta Function App em execução, com os endpoints do Swagger destacados em vermelho:
Com a interface gráfica do Swagger também sendo acessada via browser:
