Novidades do .NET 10: suporte ao uso de YAML com OpenAPI em aplicações ASP.NET Core

Embora seu uso mais comum esteja associado a representações no formato JSON, o padrão OpenAPI também suporta YAML como forma de descrever a estrutura de APIs REST. Soluções de API Gateway como o Azure API Management apresentam compatibilidade com ambos os formatos, sendo talvez YAML uma opção com uma maior legibilidade ao detalhar a forma como APIs encontram-se estruturadas.

Com o .NET 10 o package Microsoft.AspNetCore.OpenApi também passou a suportar esses 2 formatos (antes apenas JSON era oferecido como alternativa), permitindo assim que APIs REST baseadas em ASP.NET Core também exponham um endpoint para suas especificações OpenAPI no formato YAML.

Na listagem a seguir podemos observar o arquivo .csproj de uma aplicação de testes criada com .NET 10 + Minimal APIs, com o pacote Microsoft.AspNetCore.OpenApi atualizado para uso do Preview 4 desta nova versão da plataforma .NET:

Já na próxima listagem temos a implementação da API REST que também expõe sua especificação no formato YAML:

• O uso de OpenAPI ainda é habilitado via chamada ao método AddOpenApi() (linha 5);
• A instrução app.MapOpenApi(“/openapi/{documentName}.yaml”); (linha 12) permitirá que se ative também o endpoint que expõe a especificação no formato YAML.

Ao acionar o endpoint:

http://localhost:5030/openapi/v1.yaml

Teremos como resultado a especificação OpenAPI no formato YAML (com a aplicação executada a partir do Visual Studio 2022):

Clique nesta imagem para visualizar com uma melhor resolução

Este exemplo foi disponibilizado no GitHub:

https://github.com/renatogroffe/ASPNETCore10-OpenApiYAML_Saudacao

Caso achem útil esta solução, peço por favor um ⭐️ no repositório apoiando. Fica também o convite para que vocês me sigam lá no GitHub!

E apresentado também em um vídeo recente do Canal .NET:

Lembro ainda que publiquei outros artigos sobre novidades do .NET 10 aqui no blog:

Novidades do C# 14: Null-conditional assignment

Novidades do .NET 10: melhorias na ordenação numérica de strings

.NET 10: primeiros testes com o Preview 1 + melhorias na manipulação de datas com ISOWeek

Referências

Generate OpenAPI documents in YAML format | dotnet/core GitHub