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

shape
shape
shape
shape
shape
shape
shape
shape

روش کار با Swagger با asp.net core

در این مطلب قصد داریم در مورد استفاده از Swagger با Asp.Net Core توضیح دهیم

Swagger یک ابزار است که به صورت اتوماتیک ابزار مستندات سازی Api را تولید می کند، نکه ی مهم این ابزار این است که در 2 خط تنظیم می شود فقط پیچیدگی این ابزار زمانی است که یک سری اطلاعات اضافه کردید باید به تک تک خط های 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 استفاده می کنید می توانید 3 تا ردیف را کنار هم بنویسید و آن 3 ردیف و یک مجموعه کنید زمانی که می خواهید یک توضیح بدهید باید در یک پاراگراف متن را بنویسید مثل مثال بالا باید یک خط بزارید که حالت کامنت شود و بعد از آن از یک 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 یک پاسخی را بر می گرداند به طور مثال 200 به معنی این است که می خواهید یک سری مستندات ارائه دهید ویا اگر 400 را بر گرداند یک پارامتر خاص را در یک شرایط خاص برمی گرداند.

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

این نکته را توجه داشته باشید که نیازی نیست حتما باز گشت 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درست کار کند.

منبع

پاسخی بگذارید

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