Minimal API's در دات نت 6 - قسمت ششم - غنی سازی اطلاعات Swagger
اندازه‌ی قلم متن
تخمین مدت زمان مطالعه‌ی مطلب: هفت دقیقه

در ادامه‌ی بررسی نکات مرتبط با Minimal API's در دات نت 6، در این قسمت به افزودن متادیتای قابل درک توسط Open API و Swagger خواهیم پرداخت. معادل این نکات را در MVC، در سری «مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger» پیشتر مشاهده کرده‌اید.


معادل IActionResult در Minimal API's

در Minimal API's دیگر خبری از IActionResult‌ها نیست؛ اما بجای آن IResult را داریم. برای مثال فرض کنید می‌خواهیم بدنه‌ی lambda expression دو endpoint ای را که تا این مرحله توسعه دادیم، تبدیل به دو متد مجزای private کنیم:
public class AuthorModule : IModule
{
    public IEndpointRouteBuilder RegisterEndpoints(IEndpointRouteBuilder endpoints)
    {
        endpoints.MapGet("/api/authors",
            async (IMediator mediator, CancellationToken ct) => await GetAllAuthorsAsync(mediator, ct));

        endpoints.MapPost("/api/authors",
            async (IMediator mediator, AuthorDto authorDto, CancellationToken ct) =>
                await CreateAuthorAsync(authorDto, mediator, ct));

        return endpoints;
    }

    private static async Task<IResult> CreateAuthorAsync(AuthorDto authorDto, IMediator mediator, CancellationToken ct)
    {
        var command = new CreateAuthorCommand { AuthorDto = authorDto };
        var author = await mediator.Send(command, ct);
        return Results.Ok(author);
    }

    private static async Task<IResult> GetAllAuthorsAsync(IMediator mediator, CancellationToken ct)
    {
        var request = new GetAllAuthorsQuery();
        var authors = await mediator.Send(request, ct);
        return Results.Ok(authors);
    }
}
در اینجا خروجی متدها، از نوع IResult شده‌است و برای تهیه‌ی یک چنین خروجی می‌توان از کلاس استاتیک توکار جدیدی به نام Results، استفاده کرد که برای مثال بجای return OK پیشین، اینبار به همراه Results.Ok است. یکی از مزیت‌های مهم استفاده‌ی از کلاس Results، مشخص کردن صریح نوع Status Code بازگشتی از endpoint است (برای مثال Ok یا 200 در اینجا) و در کل شامل این متدها می‌شود:
Challenge, Forbid, SignIn, SignOut, Content, Text,
Json, File, Bytes, Stream, Redirect, LocalRedirect, StatusCode
NotFound, Unauthorized, BadRequest, Conflict, NoContent, Ok
UnprocessableEntity, Problem, ValidationProblem, Created
CreatedAtRoute, Accepted, AcceptedAtRoute

یک مثال: استفاده از متد Results.Problem جهت بازگشت پیام خطایی به کاربر:
try
{
    return Results.Ok(await data.GetUsers());
}
catch (Exception ex)
{

    return Results.Problem(ex.Message);
}


ساده سازی تعاریف هندلرهای endpoints در Minimal API's

تا اینجا هندلرهای یک endpoint را تبدیل به متدهایی مستقل کردیم و به صورت زیر فراخوانی شدند:
endpoints.MapGet("/api/authors",
async (IMediator mediator, CancellationToken ct) => await GetAllAuthorsAsync(mediator, ct));
این مورد را حتی به صورت زیر نیز می‌توان ساده کرد:
endpoints.MapGet("/api/authors", GetAllAuthorsAsync);
endpoints.MapPost("/api/authors", CreateAuthorAsync);
یعنی تنها ذکر نام متد پیاده سازی کننده‌ی هندلر هم در اینجا کفایت می‌کند.


غنی سازی اطلاعات Open API در Minimal API's

در اینجا چون با کنترلرها و اکشن متدها کار نمی‌کنیم، نمی‌توانیم اطلاعات تکمیلی Open API را از طریق بکارگیری attributes مخصوص آن‌ها اضافه کنیم. اولین تغییری که در Minimal API's جهت دریافت متادیتای endpoints قابل مشاهده‌است، چند سطر زیر است:
public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddApplicationServices(this IServiceCollection services,
        WebApplicationBuilder builder)
    {
        builder.Services.AddEndpointsApiExplorer();
        builder.Services.AddSwaggerGen();

        // ...
متد AddEndpointsApiExplorer که جزئی از قالب استاندارد پروژه‌های Minimal API's است، کار ثبت سرویس‌های توکار خواندن متادیتای endpoints را انجام می‌دهد و این متادیتاها اینبار توسط یکسری متد الحاقی قابل تعریف هستند:
public class AuthorModule : IModule
{
    public IEndpointRouteBuilder RegisterEndpoints(IEndpointRouteBuilder endpoints)
    {
        endpoints.MapGet("/api/authors",
                async (IMediator mediator, CancellationToken ct) => await GetAllAuthorsAsync(mediator, ct))
            .WithName("GetAllAuthors")
            .WithDisplayName("Authors")
            .WithTags("Authors")
            .Produces(500);

        endpoints.MapPost("/api/authors",
                async (IMediator mediator, AuthorDto authorDto, CancellationToken ct) =>
                    await CreateAuthorAsync(authorDto, mediator, ct))
            .WithName("CreateAuthor")
            .WithDisplayName("Authors")
            .WithTags("Authors")
            .Produces(500);

        return endpoints;
    }
نمونه‌ای از این متدهای الحاقی را که جهت تعریف متادیتای مورد نیاز Open API بکار می‌روند، در مثال فوق مشاهده می‌کنید و سرویس‌های AddEndpointsApiExplorer، کار خواندن اطلاعات تکمیلی این متدها را انجام می‌دهند.
البته اگر تا اینجا برنامه را اجرا کنید، برای مثال نام‌هایی که تعریف شده‌اند، در Swagger ظاهر نمی‌شوند. برای رفع این مشکل می‌توان به صورت زیر عمل کرد:
builder.Services.AddSwaggerGen(options =>
{
   options.SwaggerDoc("v1", new OpenApiInfo { Title = builder.Environment.ApplicationName, Version = "v1" });
   options.TagActionsBy(ta => new List<string> { ta.ActionDescriptor.DisplayName! });
});
این تغییر علاوه بر تنظیم نام و نگارش رابط کاربری Swagger، سبب می‌شود تا هر دو endpoint تعریف شده، ذیل DisplayName تنظیمی به نام Author ظاهر شوند:



تغییر خروجی endpoints از مدل دومین، به یک Dto

در endpoints فوق، اطلاعات دریافتی از کاربر، یک dto است که توسط AutoMapper به مدل دومین، نگاشت می‌شود. اینکار خصوصا از دیدگاه امنیتی جهت رفع مشکلی به نام mass assignment و عدم مقدار دهی خودکار خواصی از مدل اصلی که نباید مقدار دهی شوند، بسیار مفید است. در حین بازگشت اطلاعات به کاربر نیز باید چنین رویه‌ای درنظر گرفته شود. برای مثال مدل User می‌تواند به همراه آدرس ایمیل و کلمه‌ی عبور هش شده‌ی او نیز باشد و نباید API ما این اطلاعات را بازگشت دهد. بازگشتی از آن باید بسیار کنترل شده و صرفا بر اساس نیاز مصرف کننده تنظیم شود. به همین جهت یک Dto مخصوص را نیز برای بازگشت اطلاعات از سرور اضافه می‌کنیم تا اطلاعات مشخصی را بازگشت دهد:
namespace MinimalBlog.Api.Features.Authors;

public record AuthorGetDto
{
    public int Id { get; init; }
    public string Name { get; init; } = default!;
    public string? Bio { get; init; }
    public DateTime DateOfBirth { get; init; }
}
البته از آنجائیکه خاصیت Name این Dto، معادلی را در مدل Author ندارد تا کار نگاشت آن به صورت خودکار صورت گیرد، باید این نگاشت را به صورت دستی به نحو زیر به AuthorProfile اضافه کرد تا از طریق FullName مدل Author تامین شود:
public class AuthorProfile : Profile
{
    public AuthorProfile()
    {
        CreateMap<AuthorDto, Author>().ReverseMap();
        CreateMap<Author, AuthorGetDto>()
            .ForMember(dest => dest.Name, opt => opt.MapFrom(src => src.FullName));
    }
}
پس از این تغییر، نیاز است قسمت‌های زیر نیز در برنامه تغییر کنند:
الف) دستور و هندلر ایجاد نویسنده
public class CreateAuthorCommand : IRequest<AuthorGetDto>
در امضای دستور CreateAuthor، خروجی به Dto جدید تغییر می‌کند. بنابراین باید این تغییر در هندلر آن نیز منعکس شود:
- ابتدا نوع خروجی این هندلر نیز به AuthorGetDto تنظیم می‌شود:
public class CreateAuthorCommandHandler : IRequestHandler<CreateAuthorCommand, AuthorGetDto>
- سپس نوع بازگشتی متد Handle آن تغییر می‌کند:
public async Task<AuthorGetDto> Handle(CreateAuthorCommand request, CancellationToken cancellationToken)
- در آخر بجای return toAdd قبلی، با استفاده از AutoMapper، کار نگاشت شیء مدل Authore به شیء Dto جدید را انجام می‌دهیم:
return _mapper.Map<AuthorGetDto>(toAdd);

ب) کوئری و هندلر بازگشت لیست نویسنده‌ها
public class GetAllAuthorsQuery : IRequest<List<AuthorGetDto>>
در امضای کوئری بازگشت لیست نویسنده‌ها، خروجی به لیستی از Dto جدید تغییر می‌کند که این مورد باید به هندلر آن هم اعمال شود. بنابراین در ابتدا نوع خروجی این هندلر نیز به AuthorGetDto تنظیم می‌شود و سپس نوع بازگشتی متد Handle آن تغییر می‌کند. در آخر با استفاده از AutoMapper، لیست دریافتی از نوع مدل به لیستی از نوع Dto تبدیل خواهد شد:
public class GetAllAuthorsHandler : IRequestHandler<GetAllAuthorsQuery, List<AuthorGetDto>>
{
    private readonly MinimalBlogDbContext _context;
    private readonly IMapper _mapper;

    public GetAllAuthorsHandler(MinimalBlogDbContext context, IMapper mapper)
    {
        _context = context ?? throw new ArgumentNullException(nameof(context));
        _mapper = mapper ?? throw new ArgumentNullException(nameof(mapper));
    }

    public async Task<List<AuthorGetDto>> Handle(GetAllAuthorsQuery request, CancellationToken cancellationToken)
    {
        var authors = await _context.Authors.ToListAsync(cancellationToken);
        return _mapper.Map<List<AuthorGetDto>>(authors);
    }
}
بعد از این تغییرات می‌توان با استفاده از متد الحاقی Produces، متادیتای نوع خروجی دقیق endpoints را هم مشخص کرد:
endpoints.MapGet("/api/authors",
                async (IMediator mediator, CancellationToken ct) => await GetAllAuthorsAsync(mediator, ct))
            .WithName("GetAllAuthors")
            .WithDisplayName("Authors")
            .WithTags("Authors")
            .Produces<List<AuthorGetDto>>()
            .Produces(500);

endpoints.MapPost("/api/authors",
                async (IMediator mediator, AuthorDto authorDto, CancellationToken ct) =>
                    await CreateAuthorAsync(authorDto, mediator, ct))
            .WithName("CreateAuthor")
            .WithDisplayName("Authors")
            .WithTags("Authors")
            .Produces<AuthorGetDto>()
            .Produces(500);
که اطلاعات آن در قسمت schema ظاهر خواهد شد:



پوشه بندی Features


تا اینجا تمام فایل‌های متعلق به ویژگی Authors را در همان پوشه اصلی آن قرار داده‌ایم. در ادامه می‌توان به ازای هر ویژگی خاص، 4 پوشه‌ی Commands مخصوص Commands الگوی CQRS، پوشه‌ی Models مخصوص تعریف DTO's، پوشه‌ی Profiles مخصوص افزودن پروفایل‌های AutoMapper و پوشه‌ی Queries مخصوص تعریف کوئری‌های الگوی CQRS را به نحوی که در تصویر فوق مشاهده می‌کنید، به پروژه‌ی API اضافه کنیم.


پیاده سازی ویژگی Blogs

این پیاده سازی چون به همراه نکات جدیدی نیست و به همراه تعریف ماژول اصلی ویژگی، endpoints و الگوی CQRS ای است که تاکنون بحث شد، کدهای آن، به همراه کدهای پروژه‌ی اصلی این پروژه که از قسمت اول قابل دریافت است، ارائه شده‌است.
  • #
    ‫۱ سال و ۶ ماه قبل، شنبه ۸ بهمن ۱۴۰۱، ساعت ۲۱:۴۳
    یک نکته‌ی تکمیلی: اضافه شدن پشتیبانی از IResult به ASP.NET Core MVC 7x

    خروجی‌های اکشن متدهای MVC به همراه IActionResult و <ActionResult<T هستند و در minimal APIs که نمونه‌ای از آن‌را در این مطلب مشاهده کردید، از نوع IResult و <IValueHttpResult<TValue و ... این دو نباید با هم مخلوط شوند!
    برای مثال اگر در ASP.NET Core MVC 6x چنین اکشن متدی را تهیه کنیم:
    [HttpGet(Name = "GetWeatherForecast")]
    public IResult Get()
    {
        return Results.Ok(new { Name = "My name" });
    }
    بدون مشکل کامپایل می‌شود و ... کار هم می‌کند؛ اما با خروجی زیر:
    {
      "value": {
        "name" : "My name"
      },
      "statusCode" : 200,
      "contentType" : null
    }
    به این معنا که MVC 6x، شیء از نوع IResult را به صورت متداولی serialize کرده و خروجی فوق را ارائه داده‌است.
    این مشکل یا محدودیت در MVC 7x برطرف شده‌است و اکنون خروجی زیر را تولید می‌کند:
    {
       "name" : "My name"
    }
    البته باید بخاطر داشت که با استفاده از IResult مخصوص minimal APIs در MVC 7x، یکسری از ویژگی‌های MVC مانند content negotiation و output formatters دیگر کار نخواهند کرد؛ یعنی همیشه خروجی را به صورت JSON دریافت می‌کنیم.