‫تازه‌های NET 10.: ارتقاء توصیف APIهای REST با پشتیبانی از YAML در OpenAPI

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.4.25258.110" />
  </ItemGroup>

</Project>

using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);

// فعال‌سازی سرویس‌های OpenAPI
builder.Services.AddOpenApi();

var app = builder.Build();

// فعال‌سازی Middleware های OpenAPI در محیط توسعه
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // فعال‌سازی Endpoint پیش‌فرض JSON (معمولاً /openapi/v1.json)
    app.MapOpenApi("/openapi/{documentName}.yaml"); // فعال‌سازی Endpoint برای فرمت YAML
}

// تعریف یک Endpoint ساده برای نمونه
app.MapGet("/saudacao", () =>
{
    var currentDate = DateTime.Now;
    string mensagem = (currentDate.DayOfWeek == DayOfWeek.Saturday ||
        currentDate.DayOfWeek == DayOfWeek.Sunday) ? "Bom final de semana!" : "Seguimos na luta!";
    var saudacao = new Saudacao(currentDate, mensagem);
    return Results.Ok(saudacao);
});

app.Run();

// تعریف یک Record برای داده پاسخ (برای سادگی)
public record Saudacao(DateTime DataHora, string Mensagem);

• builder.Services.AddOpenApi(); (خط ۵): این متد، سرویس‌های لازم برای تولید و ارائه مشخصات OpenAPI را در برنامه ثبت می‌کند. این اولین گام برای فعال‌سازی پشتیبانی از OpenAPI است.
• app.MapOpenApi(); (خط ۱۱، در صورت فعال بودن): این دستور، یک Endpoint پیش‌فرض برای ارائه مشخصات OpenAPI در فرمت JSON ایجاد می‌کند. مسیر این Endpoint معمولاً چیزی شبیه به /openapi/v1.json خواهد بود، که v1 نام سند (Document Name) پیش‌فرض است.
• app.MapOpenApi("/openapi/{documentName}.yaml"); (خط ۱۲): این دستور کلیدی، Endpoint جدیدی را برای ارائه مشخصات OpenAPI در فرمت YAML فعال می‌کند. با استفاده از این مسیر، که شامل پارامتر documentName (نام سند) است، می‌توان به مشخصات API با پسوند .yaml دسترسی پیدا کرد. به عنوان مثال، اگر نام سند v1 باشد، مسیر دسترسی به فایل YAML، /openapi/v1.yaml خواهد بود.

• خوانایی بهتر مشخصات APIها: YAML با ساختار ساده و تاکید بر دندانه‌گذاری، درک فایل‌های بزرگ و پیچیده مشخصات API را آسان‌تر می‌کند.
• سازگاری گسترده‌تر: امکان ارائه مشخصات API در هر دو فرمت JSON و YAML، سازگاری با طیف وسیع‌تری از ابزارها و پلتفرم‌های مدیریت API (مانند Azure API Management) را فراهم می‌کند.
• تسهیل همکاری: تیم‌هایی که YAML را برای مستندسازی یا پیکربندی ترجیح می‌دهند، اکنون می‌توانند به طور مستقیم از خروجی YAML برنامه‌های ASP.NET Core خود استفاده کنند.
• انعطاف‌پذیری بیشتر: توسعه‌دهندگان اکنون می‌توانند بر اساس نیاز پروژه یا ترجیحات تیم، فرمت مناسب برای ارائه مشخصات API خود را انتخاب کنند.