استفاده از Swagger با Asp.Net Core

Swagger یک ابزار است که به صورت اتوماتیک ابزار مستندات سازی Api را تولید می کند، نکه ی مهم این ابزار این است که در ۲ خط تنظیم می شود فقط پیچیدگی این ابزار زمانی است که یک سری اطلاعات اضافه کردید باید به تک تک خط های Api را تغییر دهید و این باعث تغییر ابزار Swagger می شود.

شروع کار:

زمانی که شما یک پروژه ی جدید را در visual باز کنید فقط از قالب استاندارد Asp.net Core Web Api استفاده می کنید اما هر Apiکار مخصوص خودش را انجام می دهد.

ابتدا باید بسته ی Nuget خودتان را نصب کنید.

 

بعد در متد ConfigureServices از کلاس Startup.cs، کد زیر را اضافه کنید تا سرویس Swagger را به برنامه خود اضافه نمایید.

 

در اینجا دو نکته را بیان می کنیم، اول اینکه در داخل لامبدا SwaggerGen شما می توانید جزئیات بیشتری را مشخص کنید. به عنوان مثال

 

در اینجا به ازای هر داده enum بجای استفاده از مقدار integer از مقدارString و برای همه پارامترها میتوانیم از حالت CamelCase استفاده کنید. مقادیر پیش فرض معمولا مناسبترند، اما اگر موارد خاصی برای اسناد شما وجود دارد، شما احتمالا می توانید تنظیمات را در اینجا پیدا کنید

دوم اینکه با استفاده از شی Infoobject می توانید اطلاعاتی در مورد کسی که کد را نوشته، موضوع اش ، و licence آن در یافت نمایید.

به متد Configure فایل Startup.cs بروید. متدهای “UseSwagger” و “UseSwaggerUI” را باید قبل ازمتد UseMVC فراخوانی کنید.

 

حالا برنامه و اجرا کنید و به آدرس https://localhost:{yourport}/swagger بروید اینجا باید داکیومنت API را ببینید اگر چیزی ندیدید یعنی برنامه را اشتباه انجام دادید.

کامنت های XML

اگر داکیومنت های خودشان به صورت خودکار تولید شود خیلی خوب است و اگر شما خودتان یک API بسازید

معمولا با خود همون API به تنهایی کامل است اما اگر API نیاز به توضیح بیشتری باشد می توانیم از کامنت های xml استفاده کنیم.

 

اگر از visual استفاده می کنید می توانید ۳ تا ردیف را کنار هم بنویسید و آن ۳ ردیف و یک مجموعه کنید زمانی که می خواهید یک توضیح بدهید باید در یک پاراگراف متن را بنویسید مثل مثال بالا باید یک خط بزارید که حالت کامنت شود و بعد از آن از یک param باز و بسته استفاده کنید

شما باید برنامه تان برای تولید اطلاعات XML که swagger می تواند بخواند روی پروژه راست کلیک نمایید و بعد تنظیمات را انتخاب نمایید و بعد گزینه ی Build را می زنید شما در اینجا گزینه های خروجی را می توانید ببینیدکه یک چک باکس وجود دارد که یک جعبه ی مستند ساز API می سازد و تنظیمات به صورت خودکار پر می شود.

توجه داشته باشید که این تنظمیات در هر config کردن ساخته می شود اگر قصد استفاده کردن آن را دارید باید به حالت realease تنظیم نمایید و مجددا دوباره همان کارها را انجام دهید.

اگر از visual استفاده نمی کنید و یا فقط کد را می خواهید در قسمت behindcode بزارید فقط باید خط کد زیر را در فایل Csproj اضافه کنید

 

بعد شما نیاز به بازگشت به متد ConfigureServices از startup.cs خود و اضافه کردن یک متد به IncludeXmlComments در تنظیمات Swagger خود را دارید.

 

جایی که SwaggerExample.xml فایل xml است که در تنظیمات csproj / project شما تنظیم شده است.

هنگامی که شما swagger را مشاهده می کنید حالا باید xml خود را درون مستندات ساخته شده مشاهده کنید

در کد بالا سمت راست توضیح است و یک id برای پارامترها داریم و هم چنین یک مقدار توصیفی هم نوشته شده است.

توصیف کدهای API Response

زمانی که api یک پاسخی را بر می گرداند به طور مثال ۲۰۰ به معنی این است که می خواهید یک سری مستندات ارائه دهید ویا اگر ۴۰۰ را بر گرداند یک پارامتر خاص را در یک شرایط خاص برمی گرداند.

اولین قدم این است که شما اقدامات خود را به صورت یک product برگردانید در این تمام پاسخ های ممکن را برای شما بر می گرداند در همان زمان شما می توانید آن را برای یک کد مشخص توضیح دهید به عنوان مثال اگر خطای ۴۰۰ برگردانید کلاس خاصی که خطا را توضیح می دهد را برمیگردانید به مثال زیر توجه کنید:

 

این نکته را توجه داشته باشید که نیازی نیست حتما باز گشت api را بر گردانید اما به هر حال خوب است که بدانید باز گشت api چی هست

زمانی که نخواهید پاسخ api را دریافت کنید می توانید از کامت ها دوباره استفاده نمایید.

 

حالا وقتی ما این نقطه پایانی را در Swagger بررسی میکنیم، توضیحاتی در کنار کدهای پاسخ وجود داریم.

عیب یابی

در اینجا می خواهید مشکلاتی که کاربران با آن برخورد داشته اند را و راه حل آن ها را بیان کنیم:

مثلا من چیزی در صفحه ام نمی بینم :حال راه حل آن:

اول از همه بررسی کنید که بسته ی nugget nuget Microsoft.AspNetCore.StaticFiles به طور کامل نصب شده است یا نه این مشکل خیلی از کاربران بوده است حتما آن را دوبراه نصب کنید که به طور کامل نصب شود.

من از mvc core استفاده می کنم

اگر از mvc core استفاده می کنید سپس شما حتما باید API Explorer services را اضافه کنید

به روش ConfigureServices خود در startup.cs خود مراجعه کنید

 

سپس باید این خط را اضافه کنید:

 

سپس شما باید به صورت دستی سرویس ApiExplorer را اضافه کنید

 

اگر از Attribute Routing استفاده نمی کنید

سپس Swagger برای شما کار نخواهد کرد. شما باید از روشی attribute استفاده کنید تا Swagger درست کار کند.

 

استفاده از Swagger با Asp.Net Core
5 (100%) 1 رای

(434 نوشته)

C# Programmer , Web Design And Developer , MVC , ASP.NET

فکر شما چیست؟

آدرس ایمیل شما منتشر نخواهد شد. بخشهای موردنیاز علامتگذاری شدهاند *

حاصل جمع اعداد را وارد کنید : *