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