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

شروع کار:

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

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

Install-Package Swashbuckle.AspNetCore

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

public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
 
services.AddSwaggerGen(swagger =>
{
swagger.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Title = "My First Swagger" });
});
}

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

services.AddSwaggerGen(swagger =>
{
swagger.DescribeAllEnumsAsStrings();
swagger.DescribeAllParametersInCamelCase();
swagger.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Title = "My First Swagger" });
});

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

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

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

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My First Swagger");
});
 
app.UseMvc();
}

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

کامنت های XML

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

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

/// <summary>
/// Gets a value by ID.
/// </summary>
/// <param name="id">The id of the value you wish to get.</param>
/// <returns></returns>
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}

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

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

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

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

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
<DocumentationFile>bin\Debug\netcoreapp2.0\SwaggerExample.xml</DocumentationFile>
</PropertyGroup>

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

services.AddSwaggerGen(swagger =>
{
swagger.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Title = "My First Swagger", Version = "v1" });
swagger.IncludeXmlComments(Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "SwaggerExample.xml"));
});

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

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

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

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

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

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

[HttpGet("{id}")]
[ProducesResponseType(typeof(string), 200)]
[ProducesResponseType(404)]
[ProducesResponseType(400)]
public string Get(int id)
{
return "value";
}

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

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

/// <summary>
/// Gets a value by ID.
/// </summary>
/// <param name="id">The id of the value you wish to get.</param>
/// <returns></returns>
/// <response code="200">Value returned</response>
/// <response code="404">Value was not able to be found</response>
/// <response code="400">Id was below 0</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(string), 200)]
[ProducesResponseType(404)]
[ProducesResponseType(400)]
public string Get(int id)
{
return "value";
}

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

عیب یابی

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

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

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

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

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

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

services.AddMvc();

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

	services.AddMvcCore();

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

services.AddMvcCore().AddApiExplorer();

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

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

آموزش asp.net mvc