مستندسازی و تست وب‌سرویس‌ها

مقدمه

در درس گذشته، یک وب‌سرویس کاربردی برای پایگاه داده‌ی Northwind ساختیم. این API نقاط پایانی (endpoints) مختلفی را برای کار با داده‌های مشتریان فراهم می‌کند. اما چگونه یک توسعه‌دهنده‌ی دیگر (یا حتی خود ما در آینده) می‌تواند بفهمد که این API چه قابلیت‌هایی دارد، هر نقطه پایانی چه پارامترهایی را می‌پذیرد و چه نوع داده‌ای را برمی‌گرداند؟ نوشتن مستندات به صورت دستی کاری زمان‌بر و مستعد خطا است. خوشبختانه، یک استاندارد صنعتی به نام OpenAPI (که قبلاً با نام Swagger شناخته می‌شد) برای توصیف وب‌سرویس‌های RESTful وجود دارد.

ASP.NET Core یکپارچگی فوق‌العاده‌ای با این استاندارد دارد. با استفاده از یک کتابخانه به نام Swashbuckle، ما می‌توانیم به صورت خودکار یک مستندات کامل و تعاملی برای API خود تولید کنیم. این مستندات نه تنها تمام نقاط پایانی و مدل‌های داده را توصیف می‌کند، بلکه یک رابط کاربری وب (UI) فراهم می‌کند که به ما اجازه می‌دهد تا API خود را مستقیماً از داخل مرورگر تست کنیم.

راه‌اندازی Swagger در ASP.NET Core

خبر خوب این است که اگر شما پروژه‌ی خود را با استفاده از تمپلت ASP.NET Core Web API ایجاد کرده باشید، تمام تنظیمات اولیه برای Swagger به صورت پیش‌فرض برای شما انجام شده است. بیایید نگاهی به فایل Program.cs بیندازیم.

پیکربندی سرویس‌ها

در بخش پیکربندی سرویس‌ها، دو خط اصلی مربوط به Swagger را پیدا خواهید کرد:

Program.cs (Services)

// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

• AddEndpointsApiExplorer(): این سرویس، API را برای پیدا کردن اطلاعات مربوط به نقاط پایانی (مانند مسیرها، افعال HTTP و پارامترها) بازرسی می‌کند.
• AddSwaggerGen(): این سرویس اصلی کتابخانه‌ی Swashbuckle است. این سرویس از اطلاعات به دست آمده توسط ApiExplorer استفاده کرده و یک سند JSON بر اساس مشخصات OpenAPI تولید می‌کند.

پیکربندی میان‌افزار (Middleware)

در بخش پیکربندی خط لوله‌ی درخواست، دو میان‌افزار مربوط به Swagger وجود دارد که معمولاً فقط در محیط توسعه فعال می‌شوند:

Program.cs (Pipeline)

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

• UseSwagger(): این میان‌افزار، سند JSON تولید شده را در یک آدرس مشخص (معمولاً /swagger/v1/swagger.json) در دسترس قرار می‌دهد.
• UseSwaggerUI(): این میان‌افزار، یک رابط کاربری وب زیبا و تعاملی را بر اساس آن سند JSON تولید کرده و در آدرس /swagger نمایش می‌دهد.

تست تعاملی API با Swagger UI

اکنون کافی است برنامه‌ی خود را اجرا کنید (با فشردن کلید F5). مرورگر به طور خودکار باز شده و شما به صفحه‌ی Swagger UI هدایت خواهید شد.

در این صفحه، شما لیستی از تمام کنترلرهای API خود (در اینجا CustomersController) را مشاهده می‌کنید. با باز کردن هر کنترلر، لیستی از تمام اکشن‌های آن به همراه فعل HTTP و مسیرشان نمایش داده می‌شود.

تست اکشن GET /api/Customers

1. بر روی نوار مربوط به GET /api/Customers کلیک کنید تا باز شود.
2. روی دکمه‌ی Try it out کلیک کنید.
3. سپس روی دکمه‌ی آبی رنگ Execute کلیک کنید.

Swagger UI یک درخواست HTTP GET واقعی را به API شما ارسال کرده و نتیجه را در بخش Response body نمایش می‌دهد. شما می‌توانید لیستی از تمام مشتریان را در فرمت JSON مشاهده کنید.

تست اکشن GET /api/Customers/{id}

این اکشن یک پارامتر id نیاز دارد.

1. بر روی نوار مربوط به GET /api/Customers/{id} کلیک کنید.
2. روی دکمه‌ی Try it out کلیک کنید.
3. در فیلد پارامتر id، یک شناسه‌ی مشتری معتبر از پایگاه داده Northwind (مانند ALFKI) را وارد کنید.
4. روی دکمه‌ی Execute کلیک کنید.

نتیجه، یک شیء JSON واحد خواهد بود که فقط اطلاعات مربوط به آن مشتری خاص را نمایش می‌دهد.