نحوه استفاده از OpenAPI در ASP.NET Core

از پشتیبانی داخلی OpenAPI در ASP.NET Core برای مستندسازی خودکار نقاط پایانی HTTP خود بهره ببرید. حداقل API ها نیز پشتیبانی می شوند.

ASP.NET Core 6 یک مدل میزبانی ساده را معرفی کرد که به ما اجازه می دهد API های سبک وزن با حداقل وابستگی بسازیم. این حداقل پروژه‌های API، با نوشتن کدهای کمتر دیگ بخار، راه‌اندازی سریع برنامه‌مان را آسان می‌کند. ASP.NET Core 7 با افزودن پشتیبانی از فیلترها، حداقل APIها را بیشتر بهبود بخشید.

هر وقت با APIها کار می‌کنید – از جمله حداقل APIها – اغلب می‌خواهید نقاط پایانی خود را مستند کنید. خوشبختانه، ASP.NET Core پشتیبانی داخلی از مشخصات OpenAPI ارائه می‌دهد، بنابراین می‌توانید از مزیت OpenAPI و Swagger UI برای ایجاد مستندات خوب برای همه API‌های خود استفاده کنید.

هدف این پست این است که شما را در انجام این کار شروع کنید. برای استفاده از نمونه کدهای ارائه شده در این مقاله، باید Visual Studio 2022 را در سیستم خود نصب کنید. اگر قبلاً نسخه‌ای ندارید، می‌توانید Visual Studio 2022 را از اینجا بارگیری کنید.

یک پروژه Web API حداقل در Visual Studio 2022 ایجاد کنید

ابتدا، اجازه دهید یک پروژه ASP.NET Core در Visual Studio 2022 ایجاد کنیم. این مراحل را دنبال کنید:

1. Visual Studio 2022 IDE را راه اندازی کنید.
2. روی “ایجاد پروژه جدید” کلیک کنید.
3. در پنجره “ایجاد پروژه جدید”، “ASP.NET Core Web API” را از لیست الگوهای نمایش داده شده انتخاب کنید.
4. بعدی را کلیک کنید.
5. در پنجره “پیکربندی پروژه جدید خود”، نام و مکان پروژه جدید را مشخص کنید.
6. به صورت اختیاری، بسته به تنظیمات برگزیده خود، کادر انتخاب «قرار دادن راه حل و پروژه در یک فهرست راهنمای» را علامت بزنید.
7. بعدی را کلیک کنید.
8. در پنجره «اطلاعات اضافی» که در ادامه نشان داده شده است، علامت کادری را که می‌گوید «استفاده از کنترل‌کننده‌ها…» را بردارید، زیرا در این مثال از حداقل API استفاده خواهیم کرد. تنظیم “نوع احراز هویت” را به عنوان “هیچ” (پیش فرض) بگذارید. کادرهای “پیکربندی برای HTTPS” و “فعال کردن پشتیبانی از API را فعال کنید” را علامت بزنید. در نهایت، مطمئن شوید که تیک گزینه Enable Docker را بردارید زیرا ما در اینجا از Docker استفاده نخواهیم کرد. (شکل ۱ را در زیر ببینید.)
9. روی ایجاد کلیک کنید.

شکل ۱. کادرهای چک Configure for HTTP و Enable OpenAPI Support را علامت بزنید. Authentication را روی None تنظیم کنید و سایر کادرهای بررسی را بدون علامت بگذارید.

ما از این پروژه ASP.NET Core 7 Web API برای استفاده از OpenAPI برای مستندسازی حداقل نقاط پایانی API در بخش‌های زیر استفاده خواهیم کرد.

مشخصات OpenAPI چیست؟

مشخصات OpenAPI که قبلاً به عنوان مشخصات Swagger شناخته می‌شد، یک زبان توصیف رابط برنامه‌نویسی (IDL) استاندارد، قابل خواندن ماشین و زبان برنامه‌نویسی را برای APIها تعریف می‌کند. این یک استاندارد مستقل از زبان برای توصیف API های HTTP است. این استاندارد توسط ترکیبی از APIهای داخلی و کتابخانه‌های منبع باز پشتیبانی می‌شود.

سه جنبه مهم ادغام OpenAPI در یک برنامه عبارتند از:

1. ایجاد اطلاعات در مورد نقاط پایانی برنامه.
2. قرار دادن داده ها در قالبی سازگار با استاندارد OpenAPI.
3. نمایش طرح OpenAPI ایجاد شده از طریق یک رابط کاربری گرافیکی یا یک فایل سریالی.

از آنجایی که هنگام ایجاد پروژه ASP.NET Core 7 Web API خود، پشتیبانی OpenAPI را فعال کردیم، بسته Swashbuckle.AspNetCore به طور خودکار به پروژه اضافه می شود. Swashbuckle یک پروژه منبع باز است که امکان تولید اسناد Swagger را فراهم می کند.

توجه داشته باشید که همیشه می‌توانید Swashbuckle.AspNetCore بسته NuGet را به پروژه‌های دیگر خود اضافه کنید به صورت دستی.

در ASP.NET Core یک حداقل API ساده ایجاد کنید

وقتی یک پروژه ASP.NET Core Web API جدید در ویژوال استودیو ایجاد می‌کنید، کنترلر پیش‌فرض (به نام WeatherForecast) و کلاس مدل به‌طور خودکار ایجاد می‌شوند. از آنجایی که ما در اینجا از حداقل API استفاده می کنیم، این فایل ها ایجاد نمی شوند.

در عوض، یک نقطه پایانی پیش‌فرض HTTP GET در فایل Program.cs ایجاد می‌شود. اکنون کد تولید شده پیش فرض نقطه پایانی HTTP GET را با کد زیر جایگزین کنید.

app.MapGet("/", () => "Hello World!")
.WithName("Welcome")
.WithOpenApi();

هنگامی که برنامه را اجرا می کنید، همانطور که در شکل ۲ نشان داده شده است، می توانید رابط کاربری Swagger را در مرورگر وب خود مشاهده کنید.

شکل ۲. رابط کاربری Swagger.

Swagger را در یک API حداقل در ASP.NET Core پیکربندی کنید

قطعه کد زیر نشان می‌دهد که چگونه می‌توانید میان‌افزار Swagger را برای افزودن متادیتا برای سند API پیکربندی کنید.

builder.Services.AddSwaggerGen(setup => setup.SwaggerDoc("v1", new OpenApiInfo()
{
    Description = "This is a simple implementation of a Minimal Api in Asp.Net 7 Core",
    Title = "Demo Api",
    Version = "v1",
    Contact = new OpenApiContact()
    {
        Name = "Joydip Kanjilal",
        Url = new Uri("https://joydipkanjilal.com")
    }
}));

هنگامی که اکنون برنامه را اجرا می کنید، فراداده ای که اضافه کرده اید در رابط کاربری Swagger همانطور که در شکل ۳ نشان داده شده است نمایش داده می شود.

شکل ۳. افزودن ابرداده API.

یک کلاس مدل ایجاد کنید

اکنون بیایید برنامه نمونه API حداقلی خود را کامل کنیم. ابتدا با استفاده از کد زیر یک کلاس مدل ایجاد کنید.

public class Author
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Address { get; set; }
    public string Email { get; set; }
    public string Phone { get; set; }
}

یک رابط ایجاد و پیاده سازی کنید

بعد، یک رابط به نام IAuthorRepository ایجاد کنید و کد زیر را وارد کنید.

public interface IAuthorRepository
{
    Author GetById(int id);
    void Create(Author entity);
    void Delete(Author entity);
    void Update(Author entity);
}

حالا کلاس دیگری به نام AuthorRepository ایجاد کنید و کد زیر را وارد کنید.

public class AuthorRepository : IAuthorRepository
{
    void IAuthorRepository.Create(Author entity)
    {
        throw new NotImplementedException();
    }
    void IAuthorRepository.Delete(Author entity)
    {
        throw new NotImplementedException();
    }
    Author IAuthorRepository.GetById(int id)
    {
        throw new NotImplementedException();
    }
    void IAuthorRepository.Update(Author entity)
    {
        throw new NotImplementedException();
    }
}

توجه داشته باشید که هیچ یک از متدهای کلاس AuthorRepository پیاده سازی نشده است. ما از این پیاده‌سازی اسکلت استفاده می‌کنیم تا ببینیم چگونه می‌توانیم با OpenAPI در حداقل برنامه‌های API کار کنیم.

یک حداقل نقطه پایانی API ایجاد کنید

در نهایت، نقطه پایانی را که قبلا ایجاد کرده بودیم حذف کنید زیرا دیگر به آن نیازی نداریم. در عوض، کد زیر را به فایل Program.cs خود اضافه کنید تا چهار نقطه پایانی جدید ایجاد کنید.

app.MapGet("/authors/{id}", async ([FromServices] Author entity, int id) =>
{
    return Results.Ok();
});
app.MapPost("/authors", async ([FromServices] Author entity) =>
{
    return Results.Ok();
});
app.MapPut("/authors/{id}", async ([FromServices] int id, Author entityToUpdate) =>
{
    return Results.Ok();
});
app.MapDelete("/authors/{id}", async ([FromServices] int id) =>
{
    return Results.Ok();
});

هنگامی که برنامه را اجرا می کنید، باید مانند شکل ۴، این نقاط پایانی را در Swagger UI خود مشاهده کنید.

شکل ۴. چهار نقطه پایانی حداقل API ما.

نمونه حداقل API را در ASP.NET Core کامل کنید

لیست کد کامل برای حداقل API مستند شده با OpenAPI ما برای مرجع شما در زیر آمده است.

using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddSwaggerGen(setup => setup.SwaggerDoc("v1", new OpenApiInfo()
{
    Description = "This is a simple implementation of a Minimal Api in Asp.Net 7 Core",
    Title = "Demo Api",
    Version = "v1",
    Contact = new OpenApiContact()
    {
        Name = "Joydip Kanjilal",
        Url = new Uri("https://joydipkanjilal.com")
    }
}));
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.MapGet("/authors/{id}", async ([FromServices] Author entity, int id) =>
{
    return Results.Ok();
});
app.MapPost("/authors", async ([FromServices] Author entity) =>
{
    return Results.Ok();
});
app.MapPut("/authors/{id}", async ([FromServices] int id, Author entityToUpdate) =>
{
    return Results.Ok();
});
app.MapDelete("/authors/{id}", async ([FromServices] int id) =>
{
    return Results.Ok();
});
app.Run();
public class Author
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Address { get; set; }
    public string Email { get; set; }
    public string Phone { get; set; }
}
public interface IAuthorRepository
{
    Author GetById(int id);
    void Create(Author entity);
    void Delete(Author entity);
    void Update(Author entity);
}
public class AuthorRepository : IAuthorRepository
{
    void IAuthorRepository.Create(Author entity)
    {
        throw new NotImplementedException();
    }
    void IAuthorRepository.Delete(Author entity)
    {
        throw new NotImplementedException();
    }
    Author IAuthorRepository.GetById(int id)
    {
        throw new NotImplementedException();
    }
    void IAuthorRepository.Update(Author entity)
    {
        throw new NotImplementedException();
    }
}

با فعال کردن پشتیبانی OpenAPI در پروژه‌های Web API خود هنگام ایجاد آن‌ها، می‌توانید ASP.NET Core را به طور خودکار نقاط پایانی HTTP خود را مستند کنید و می‌توانید آن اطلاعات را از طریق Swagger UI مشاهده کنید. توجه داشته باشید که می توانید رابط کاربری Swagger را با استفاده از Cascading Style Sheets سفارشی کنید، مقادیر enum را به عنوان مقادیر رشته نشان دهید و اسناد Swagger مختلف را برای نسخه های مختلف API خود ایجاد کنید.