مستند سازی api ها برای برای استفاده راحت تر دیگر برنامه نویس­ها و تیم ها تهیه می شود. وب سرویس ها و api های که توسط ما نوشته می شوند ممکن است توسط تیم دیگری از شرکت خودمان یا توسط هزاران نفر دیگر خارج از شرکت استفاده شوند. وقتی تعداد استفاده کننده ها بیشتر می شود نیاز به مستند سازی دقیقی از نحوه عملکرد api ها بیشتر حس می شود.اگر وارد سایت های مانند تلگرام یا اینستاگرام شویم می بینیم که هرکدام api های برای استفاده در اختیار عموم مردم قرار داده اند و به نحوه های مختلفی مستنداتی برای استفاده کننده نهایی ارائه داده اند. ما هم برای استفاده بهتر و راحتر از api های که تولید می کنیم باید مستنداتی برای api های نوشته شده تولید کنیم حتی اگر یک نفراز تیم خودمان قرار است از این api ها استفاده کند. این مستندات باید توضیحات کاملی در مورد افعال api ها، پارامترهای ورودی، Json خروجی  و نحوه سطح دسترسی به استفاده کننده نهایی ارائه دهد.

مستند سازی خودکارapi  ها

برای اکثر برنامه نویسان نوشتن مستندات کار دشواری است و به همین دلیل اغلب مستنداتی که تهیه می شوند ناقص و با api که از آن می خواهیم استفاده کنیم تفاوت هایی دارد و در برخی حالات ممکن است این مستندات بروزرسانی نشوند و چندین ورژن از برنامه اصلی  عقبتر باشند.

اگر شما هم وقت نوشتن و بروزرسانی مستندات برای api های خود را ندارید باید از فریم ورک ها یا کتابخانه هایی که تهیه مستندات خودکار از api های شما را انجام می دهند استفاده کنید. این فریم ورک ها حتی کار بروزرسانی مستندات api را هم انجام می دهند و شما بدون نگرانی از این قصیه می توانید تمرکز خود را روی توسعه کد بگذارید، مطمئن باشید که همیشه مستندات api های شما با آخرین تغیرات پروژه یکی هستند.Swagger یکی از این فریم ورک ها است. ما در ادامه این مقاله  به آموزش swagger می پردازیم.

Swagger چیست

Swagger یک فریم ورک است برای تولید خودکار مستندات تعاملی از api ها. Swagger  ساختار api های ما رو تشخیص میدهد و دقیقا با همان ساختار مستندات رو تولید می کند. همه جذابیت swagger در همین است که با خواندن ساختار api ها به صورت خودکار همیشه مستندات ما  را آپدیت نگه میدارد ونگرانی ما برای همگام سازی api ها و مستندات رو رفع میکند.همچنین swagger این امکان رو به ما میدهد که به صورت خودکار کد استفاده از api را برای زبان های مختلف تولید کنیم.مستندات swagger به صورت تعاملی تولید می شوند و شما برای تست دستی هر api می توانید از صفحه تولید شده توسط swagger استفاده کنید و دیگر نیازی به نرم افزارهای مانند postman برای تست api ها ندارید.

این فضای تعاملی که ایجاد شده است تمامی موارد زیر را ارائه می دهد:

• افعال http که api پشتیباتی میکند مانند Get,Post,Put,Delete
• پارامتر های ورودی api چیست؟
• خروجی api چیست؟
• آیا api نیاز به مجوز دسترسی دارد؟ در صورت وجود خود swagger امکان login و احراز هویت را دارا می باشد
• توضیحات مربوط به هر api و پارامترها

توضیحات هر api را به صورت دستی می توانیم بنویسیم و یا خود swagger به صورت خودکار از طریق کامنت های هر action این مورد رو تشخیص دهد.

نحوه استفاده از Swagger

نصب swagger بر روی asp.net core

برای نصب swagger باید پکیج Swashbuckle.AspNetCore را در پنجره Pckage Manager Console نصب کنیم.

با استفاده از کد زیر میتوانیم swagger را بر روی asp.netcore نصب کنیم.

Install-Package Swashbuckle.AspNetCore

راه اندازی swagger در asp.net core

بعد از نصب پکیج Swashbuckle.AspNetCor باید تنظیمات و کانفیک های مورد نیاز را درفایل Startup.cs اعمال کنیم. در ConfigureService باید متد AddSwaggerGen را بنویسیم.و اطلاعات کلی هم در مورد مستندات در اینجا وارد می کنیم.

 services.AddSwaggerGen(c =>
 {
   c.SwaggerDoc("v1", new Info { Title = "Values Api", Version = "v1" });
 });

پس از اعمال این تغیرات باید فایل Startup.cs همانند تصویر زیر باشد.

مرحله بعدی افزودن SwaggerUI است. این تنظیمات را در متد Configure در فایل Startup.cs انجام می دهیم. اول متد UseSwagger را استفاده می کنیم و سپس متد UseSwaggerUI و در این متد Url دسترسی به swagger را هم مشخص می کنیم.

کد زیر را به متد Configure اضافه کنید:

app.UseSwagger();
app.UseSwaggerUI(c =>
{
 c.SwaggerEndpoint("/swagger/v1/swagger.json", "Values Api V1");
});

پس از اعمال این کن باید فایل Startup.cs همانند تصویر زیر باشد.

کار با Swagger

اگر تنظیمات گفته شده را به درستی انجام داده باشیم پس از اجرای پروژه وارد لینک /Swagger می شویم ومستندات تعاملی تولید شده توسط Swagger را مشاهده می کنیم.

برای کار با Swagger وارد صفحه تولید شده  به آدرس  yoredomain.com/swagger  می شویم. این صفحه به صورت تعاملی ساخته شده است و ما می تواینم ورودی به api ها داده و آنها را صدا بزنیم و سپس خروجی را در همین صفحه مشاهده کنیم.

افزودن Token Header در Swagger 

اگر api ها ما برای دسترسی نیاز به مجوز های مانند توکن JWT داشته باشند می توانیم این قابلیت را  به swagger اضافه کنیم که بتوانیم به همراه هر درخواست token را هم با header ارسال کنیم. برای افزودن این قابلیت متد AddSwaggerGen را به صورت زیر ویرایش کنید.

services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "Values Api", Version = "v1" });
                c.AddSecurityDefinition("Bearer",
                       new ApiKeyScheme
                       {
                           In = "header",
                           Name = "Authorization",
                           Type = "apiKey"
                       });
                c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>> {
                    { "Bearer", Enumerable.Empty<string>() },
                    });

            });

حالا اگر پروژه را اجرا کنیم و وارد url مربوط به مستندات Swagger شویم در بالای صفحه سمت راست دکمه ای به نام Authorize اضافه شده است.از این دکمه برای وارد کردن توکن می توانیم استفاده کنیم.