اضافه کردن Swagger به پروژه ASP.NET Core

آیا پروژه جدیدی از نوع dotnet core api وجود دارد که از swagger استفاده نکند؟ این یکی از اولین مواردی هست که من روی پروژه نصب می کنم، حتی اگر در نهایت با ابزاری مانند Postman آن را تست کنم. من می توانم به سرعت یک GUI را نمایش دهم و امکان تست را برای testerها، سایر توسعه دهندگان و حتی مدیران پروژه فراهم کنم. و این خارق العاده است.

برای شروع کار، ابتدا باید یک پروژه ASP.net core web api ایجاد کنید و برای استفاده از ابزار swagger، بسته ای تحت عنوان Swashbuckle.AspNetCore در Nuget وجود دارد که برای نصب آن می توانید از NuGet Package Manager Console استفاده کنید.

Install-Package Swashbuckle.AspNetCore

در قدم بعد باید سرویس و Middleware مربوط به swagger را در کلاس startup تنظیم کنیم. برای این منظور می توانید از کدهای زیر استفاده کنید.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc(&quotv1&quot, new Microsoft.OpenApi.Models.OpenApiInfo
    {
         Version = &quotv1&quot,
         Title = &quotSwagger Demo&quot,
         Description = &quotSwagger Demo&quot,
         TermsOfService = new System.Uri(&quothttps://example.com/terms&quot),
         Contact = new Microsoft.OpenApi.Models.OpenApiContact()
         {
             Name = &quotMohsen Farokhi&quot,
             Email = &quotM.farokhi@outlook.com&quot,
             Url = new System.Uri(&quothttps://www.linkedin.com/in/mohsen-farokhi&quot),
          },
          License = new Microsoft.OpenApi.Models.OpenApiLicense
          {
              Name = &quotUse under LICX&quot,
              Url = new System.Uri(&quothttps://example.com/license&quot),
           }
     });
     c.AddSecurityDefinition(&quotBearer&quot, new Microsoft.OpenApi.Models.OpenApiSecurityScheme
     {
             Description = &quotJWT Authorization header using the Bearer scheme.&quot,
             Name = &quotAuthorization&quot,
             In = Microsoft.OpenApi.Models.ParameterLocation.Header,
             Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey,
              Scheme = &quotBearer&quot
      });
       c.AddSecurityRequirement(new Microsoft.OpenApi.Models.OpenApiSecurityRequirement()
       {
             {
                 new Microsoft.OpenApi.Models.OpenApiSecurityScheme
                  {
                            Reference = new Microsoft.OpenApi.Models.OpenApiReference
                            {
                                Type = Microsoft.OpenApi.Models.ReferenceType.SecurityScheme,
                                Id = &quotBearer&quot
                            },
                                Scheme = &quotoauth2&quot,
                                Name = &quotBearer&quot,
                                In = Microsoft.OpenApi.Models.ParameterLocation.Header,
                            },
                            new System.Collections.Generic.List<string>()
                    }
            });
       var xmlPath = System.IO.Path.Combine(System.AppContext.BaseDirectory, &quotApplication.xml&quot);
       c.IncludeXmlComments(xmlPath);
});

در بخش سرویس ها می توانید مشخصات خود یا اطلاعات دلخواه خود را جایگزین کد موجود کنید. در قسمت Middleware علاوه بر اضافه کردن Swagger، باید SwaggerUI را نیز برای ایجاد صفحه تست اضافه کنید.

کافی است با فشردن کلیدهای F5 یا Ctrl+F5 یا اجرای دستور dotnet run در cmd پروژه خود را run کنید. برای مشاهده و تست APIها می توانید به آدرس اجرا شده و مسیر swagger/ بروید. تصویر زیر نمونه ای از خروجی این ابزار است:

اگر می خواهید به صورت پیش فرض پس از اجرای پروژه، آدرس swagger/ باز شود می توانید به تنظیمات پروژه خود بروید و همانند تصویر زیر در بخش Debug در فیلد Launch browser مقدار swagger را وارد کنید.

برای افزودن فیلد توکن برای احراز هویت به Swagger می توانید کدهای زیر را به تنظیمات سرویس swagger در تابع ConfigureServices کلاس Startup اضافه کنید.

c.AddSecurityDefinition(&quotBearer&quot, newMicrosoft.OpenApi.Models.OpenApiSecurityScheme
{
    Description = &quotJWT Authorization header using the Bearer scheme.&quot,
    Name = &quotAuthorization&quot,
    In = Microsoft.OpenApi.Models.ParameterLocation.Header,
    Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey,
    Scheme = &quotBearer&quot
});
c.AddSecurityRequirement(new Microsoft.OpenApi.Models.OpenApiSecurityRequirement()
{
    {
        new Microsoft.OpenApi.Models.OpenApiSecurityScheme
        {
            Reference = newMicrosoft.OpenApi.Models.OpenApiReference
            {
                Type = Microsoft.OpenApi.Models.ReferenceType.SecurityScheme,
                Id = &quotBearer&quot
            },
            Scheme = &quotoauth2&quot,
            Name = &quotBearer&quot,
            In = Microsoft.OpenApi.Models.ParameterLocation.Header,
        },
        new List<string>()
    }
});

برای نمایش کامنت های XML در swagger می توانید مسیر ذخیره سازی کامنت های XML را در تنظیمات پروژه ی خود تنظیم کنید. همچنین اگر می خواهید هشداری در مورد عدم گذاشتن کامنت در برخی از توابع action های خود دریافت نکنید مقدار 1591 را به انتهای فیلد Suppress warning اضافه کنید.

برای تنظیم نمایش کامنت ها در swagger باید کد زیر را به تابع ConfigureServices در کلاس Startup اضافه کنید.

var xmlPath = Path.Combine(AppContext.BaseDirectory, &quot SwaggerApplication.xml&quot);
c.IncludeXmlComments(xmlPath);

اکنون می توانید کامنت هایی به پروژه خود اضافه کنید.

/// <summary>
/// Get action method that accepts an integer as an argument
/// </summary>
/// <param name=&quotid&quot></param>
/// <returns></returns>
[HttpGet(&quot{id}&quot)]
public async Task<ActionResult<TodoItem>> GetTodoItem(int id)
{
    var todoItem = await _todoItemService.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }
    return Ok(todoItem);
}

پس از اجرای پروژه می توانید کامنت های مربوط به هر API را نیز می توانید در swagger مشاهده کنید.

همچنین می توانید به مستندات خود با استفاده از المنت <remarks> یک نمونه برای request متد خود مشخص کنید.

/// <remarks>
/// POST / TodoItems
/// {
/// &quotid&quot: 1,
/// &quotname&quot: &quotItem1&quot,
/// &quotisComplete&quot: true
/// }
/// </remarks>

اکشن Post در تصویر زیر، در صورت موفقیت آمیز بودن عملیات کد 200 را به عنوان خروجی برمی گرداند و اگر request body دارای مقدار null باشد کد 400 را بر می گرداند. بدون مستند سازی مناسب، استفاده کننده از نتایج نهایی اطلاع نخواهد داشت. با اضافه کردن خطوط زیر می توانیم این مشکل را حل کنیم.

/// <response code=&quot200&quot>Returns the newly created item</response>
/// <response code=&quot400&quot>If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public asyncTask<IActionResult> Insert(TodoItem todoItem)
{
    await_todoItemService.InsertAsync(todoItem);
    return Ok(todoItem);
}