همواره یکی از مشکلات برنامه نویسان برای استفاده از APIها (در اینجا منظور وب سرویس ها می باشد) مشخص نبودن نحوه استفاده از متدهای ارائه شده و اصلا کاربرد هر یک از آنها می باشد. اکثر ما تجربه کار با APIهای پرداخت آنلاین بانک های مختلفی را داشته ایم. آدرس وب سرویس ها داده می شود و شما باید از سرویس های مورد نیاز ارائه شده در این آدرس استفاده کنید، بدون اینکه راهنمای مناسبی داشته باشید. بعد از دسترسی به سرویس ها باید به دنبال فایل راهنمای استفاده از آنها باشید که هر کدام چه کاری را انجام می دهند و مقادیر ورودی و خروجی آنها چگونه می باشد.(حالا این فایل راهنما برای نسخه آخر ارائه شده می باشد یا برای نسخه های قبلی است.)
برای طرف های ارائه دهنده وب سرویس هم دشواری های زیادی برای بحث مستندسازی و تولید راهنمای بروز برای سرویس های خود وجود دارد. آیا برنامه نویسان فایل word راهنما را طبق تغییرات کد خود به روز کرده اند یا نه و آیا این نسخه آخر از فایل راهنما به دست مصرف کنندگان از API رسیده است یا خیر!؟
همه این مشکلات باعث شده تا ابزاری بسیار کاربردی برای تولید راهنما استفاده از API ایجاد شود که دو طرف نیز در استفاده از لذت خواهند برد.
Swagger چیست ؟
یک ابزار بسیار قوی برای ساخت راهنمای آنلاین و نمایش شماتیک API ها (سرویس های تحت وب مخصوصا WebAPI) می باشد که محبوبیت خیلی زیادی بین کاربران خود داشته است به طوریکه برای 25 زبان توسعه داده شده است. در اینجا می خواهیم نحوه استفاده از آن را در ASP.NET Core بر روی dotNET Framework نشان دهیم. از Swagger می توانید در ASP.NET MVC نیز براحتی استفاده نمائید(با استفاده از نصب nuget Package آن).
برای شروع یک پروژه ASP.NET Core WebApplication بر روی بستر dotNET Framework طبق تصویر زیر ایجاد می نمائیم.
سپس در پروژه ایجاد شده و در بخش SolutionExplorer فایل priject.json را باز کرده و کد زیر را در آن اضافه می نمائیم. با این تغییر package مربوط به Swagger به پروژه اضافه خواهد شد. ("Swashbuckle": "6.0.0-beta902"). پس از افزودن این خط به انتهای فایل، باید تغییرات فایل را ذخیره (ctrl + s) نمایید تا package مورد نظر بر روی پروژه Restore گردد.
پس از مرحله نصب package حالا برای استفاده از package، باید آن را در فایل Startup.cs نیز برای استفاده معرفی نمائیم و تغییراتی در این فایل ایجاد نمائیم. در ابتدا باید قطعه کد services.AddSwaggerGen را در ConfigureServices طبق تصویر زیر اضافه نمائیم.
|
1
2
3
4
5
6
7
|
public void ConfigureServices(IServiceCollection services){ // Add framework services. services.AddApplicationInsightsTelemetry(Configuration); services.AddMvc(); services.AddSwaggerGen();} |
سپس دو خط زیر را در متد Configure اضافه نمائیم :
|
1
2
3
4
5
6
7
8
9
10
11
12
|
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory){ loggerFactory.AddConsole(Configuration.GetSection("Logging")); loggerFactory.AddDebug(); app.UseApplicationInsightsRequestTelemetry(); app.UseApplicationInsightsExceptionTelemetry(); app.UseMvc(); app.UseSwagger(); app.UseSwaggerUi();} |
نکته : در مرحله تست می توانید براحتی طبق تصویر زیر آدرس پیش فرض خود را به آدرس بالا تغییر دهید تا در هر بار اجرای پروژه صفحه مربوطه به راهنمای APIها نمایش داده شود.برای اعمال این تغییر بر روی نام پروژه خود در Solution Explorer کلیک راست کرده و گزینه Properties را انتخاب نمائید و در قسمت Debug تغییر زیر را ایجاد نمائید.
حالا پروژه خود را اجرا نمائید.باید مانند تصویر زیر را مشاهده نمائید. شما هم حتما مثل من که اولین بار از Swagger استفاده نمودم تعجب نمائید که داشتن یک راهنمای گرافیکی و مشخص برای WebAPI چقدر ساده بود و ما قبل از آن چقدر بر سر درست کردن راهنما دشواری می کشیدیم. شما در تصویر زیر به تعداد Controller های api که نوشته باشید یک سطر اضافه می گردد که نشان دهنده یک controller می باشد که در ادامه هم متدهای آن controller را مشاهده می نمائید.
حالا می خواهیم کمی توضیحات هم برای راهنمایی بهتر به این صفحه اضافه نمائیم. در ابتدا توضیحات در رابطه با شرکتی که این سرویس را ارائه می کند و چه کسی این را نوشته و اطلاعات تماس برنامه نویس API را در صورت نیاز طبق کدهای زیر در کلاس Startup اضافه می نمائیم.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
public void ConfigureServices(IServiceCollection services){ // Add framework services. services.AddApplicationInsightsTelemetry(Configuration); services.AddMvc(); services.AddSwaggerGen(); services.ConfigureSwaggerGen(options => { options.SingleApiVersion(new Info { Version = "v1", Title = "SepidAria API", Description = "My First ASP.NET Core Web API", TermsOfService = "None", Contact = new Contact() { Name = "Mohsen Derambakht",Email = "info@sepidaria.com", Url = "www.sepidaria.com" } }); });} |
مجدد پروژه خود را اجرا نمائید و در بالای صفحه توضیحات گذاشته شده را مشاهده خواهید کرد.
این هم از توضیح برای صفحه راهنمای وب سرویس های خود. در نهایت می خواهیم برای هر خط از سرویس های خود نیز توضیحاتی بیاوریم. توضیحات مانند شرح یک سرویس، خطاهای و پیغام های دریافتی و موارد دیگر. می خواهیم از توضیحات summary که بالای هر متد که اکثر برنامه نویس ها توضیحاتی می نویسند استفاده نمائیم و آنها را در نیز در صفحه راهنما نمایش دهیم.
برای این کار ابتدا به صفحه Properties پروژه می رویم و این بار قسمت Build را انتخاب می نمائیم. سپس طبق تصویر زیر در انتهای صفحه گزینه
XML documentation file را تیک می زنیم.
اضافه نمائید.
|
1
2
3
4
5
|
private string GetXmlCommentsPath(){ var app = PlatformServices.Default.Application; return System.IO.Path.Combine(app.ApplicationBasePath, "ProjectName.xml");} |
نکته : لطفا دقت فرمائید که در انتهای خط چهارم در کدهای بالا به جای ProjectName نام پروژه خود را که در SolutionExplorer دیده می شود را قرار دهید.
حالا باید متد ConfigureService را در همین فایل به شکل زیر تغییر دهید:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
public void ConfigureServices(IServiceCollection services){ // Add framework services. services.AddApplicationInsightsTelemetry(Configuration); var xmlPath = GetXmlCommentsPath(); services.AddMvc(); services.AddSwaggerGen(); services.ConfigureSwaggerGen(options => { options.SingleApiVersion(new Info { Version = "v1", Title = "SepidAria API", Description = "My First ASP.NET Core Web API", TermsOfService = "None", Contact = new Contact() { Name = "Talking Dotnet", Email = "Mohsen Derambakht", Url = "www.sepidaria.com" } }); options.IncludeXmlComments(xmlPath); });} |
به سراغ controller مورد نظر خود بروید و برای یکی از متدها خود توضیحی مانند کد زیر قرار دهید :
|
1
2
3
4
5
6
7
8
9
10
|
// DELETE api/values/5/// <summary>/// Delete API Value/// </summary>/// <remarks>This API will delete the values.</remarks>/// <param name="id"></param>[HttpDelete("{id}")]public void Delete(int id){} |
مجدد پروژه را اجرا نمائید. من در پروژه خود دو کنترلر اضافه نمودم و برای متدهای کنترلر Product خود توضیحاتی را قرار دادم.
در تصویر زیر یک راهنمای تقریبا کامل را مشاهده می نمائید.
امیدوارم که این مقاله برای شما نیز مفید باشد و دیگر برای ساختن راهنما برای سرویس های خود از Swagger استفاده نمائید.
در این مقاله با Swapper و نحوه استفاده از آن آشنا شدیم. مهم ترین مزیت Swagger ، همیشه در دسترس بودن و بروز بودن راهنمای API های شما می باشد.
آموزش حرفه ای ASP.NET Core 5
