Swagger یک ابزار کامل برای مستندسازی Api هاست. با استقاده از Swagger میتوانید لیست Api های خود را نمایش دهید. Swagger اطلاعات کاملی درباره نحوه استفاده از Api ها را در اختیار شما قرار میدهد. ورودی Api ها و خروجی آنها را مشخص می کند. دیگر نیازی نیست برای Api های خود یک PDF برای نحوه کار کردن با Api ها درست کنید!. Swagger امکان تست Api هارا نیز بر روی وبسایت فراهم میکند. اگر Api های شما نیاز به توکن داشته باشند میتوانید این قابلیت Swagger را فعال کنید که هنگام فراخوانی Api ها توکن را در هدر درخواست ها قرار دهد. و کلی امکانات دیگه ...

برای استفاده از Swagger یک پروژه جدید از نوع ASP.NET Core Web Application ایجاد کنید. در ادامه ورژن دات نت کور را بر روی 2.1 قرار دهید. سپس پکیج های زیر را جهت استفاده از Swagger نصب کنید.

<PackageReference Include="Swashbuckle.AspNetCore" Version="4.0.1" />
<PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="4.0.1" />
<PackageReference Include="Swashbuckle.AspNetCore.Filters" Version="4.5.2" />

در ادامه یک پوشه به نام SwaggerConfig ایجاد میکنیم و یک کلاس به نام SwaggerExtensions برای کانفیگ Swagger در آن ایجاد میکنیم. کلاس ایجاد شده به صورت زیر است :

public static class SwaggerExtensions
{
    public static void AddSwagger(this IServiceCollection services)
    {
        services.AddSwaggerGen(options =>
        {
            options.EnableAnnotations();
            options.SwaggerDoc("v1", new Info { Version = "v1", Title = "Swagger Example" });
        });
    }
    public static void UseSwaggerAndUI(this IApplicationBuilder app)
    {
        app.UseSwagger();
        app.UseSwaggerUI(options =>
        {
            options.DocExpansion(DocExpansion.None);
            options.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger Example Docs");
        });
    }
}

در این کلاس از دو اکستنشن متد برای جلوگیری از شلوغ شدن کلاس Startup و خوانایی بهتر کد استفاده کرده ایم و در کلاس Startup فقط این متدها را فراخوانی میکنیم. در ادامه کلاس Startup به صورت زیر است.

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    services.AddSwagger();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseSwaggerAndUI();
    app.UseHttpsRedirection();
    app.UseMvc();
}

اکنون اگر برنامه را اجرا کنید و به مسیر Swagger/ بروید لیست Api هایی که در پروژه ایجاد کرده اید را مشاهده خواهید کرد. 

اما لیست Api های شما برای همه قابل مشاهده است. برای جلوگیری از این کار میتوانید به صورت زیر عمل کنید تا فقط کاربرانی که لاگین کرده اند بتوانند لیست Api هارا ببینند. میتوانید این کار را نیز بر اساس نقش آنها تنظیم کنید.

public static void AddSwagger(this IServiceCollection services)
{
    services.AddSwaggerGen(options =>
    {
        options.EnableAnnotations();
        options.DocumentFilter<AuthenticationDocumentFilter>();
        options.SwaggerDoc("v1", new Info { Version = "v1", Title = "Swagger Example" });
    });
}

در متد AddSwaggerGen از DocumentFilter استفاده کرده‌ایم. با استفاده از Document FIlter‌ها میتوانید خروجی api‌ها را در swagger، توسعه دهید. DocumentFilter که از نوع جنریک است، یک کلاس را به عنوان تایپ قبول میکند که باید از اینترفیس IDocumentFilter ارث بری کرده باشد. اینترفیس IDocumentFilter حاوی یک متد Apply است که دارای دو ورودی از نوع SwaggerDocument  و DocumentFilterContext میباشد. کلاس SwaggerDocument  مستندات api‌ها را در اختیار شما قرار میدهد و میتوانید آنهارا تغییر دهید. سپس کلاس AuthenticationDocumentFilter را پیاده سازی میکنیم: 

public class AuthenticationDocumentFilter : IDocumentFilter
{
    private readonly IHttpContextAccessor httpContextAccessor;

    public AuthenticationDocumentFilter(IHttpContextAccessor httpContextAccessor)
    {
        this.httpContextAccessor = httpContextAccessor;
    }

    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        if (!httpContextAccessor.HttpContext.User.Identity.IsAuthenticated)
        {
            swaggerDoc.Definitions = new Dictionary<string, Schema>();
            swaggerDoc.Paths = new Dictionary<string, PathItem>();
        }
    }
}

در کلاس AuthenticationDocumentFilter از IHttpContextAccessor برای دسترسی به هویت کاربر استفاده کرده ایم که بعدا باید در متد ConfigureService متد AddHttpContextAccessor را جهت دسترسی به IHttpContextAccessor فراخوانی کنیم. در ادامه اگر کاربر لاگین نکرده باشد، تمامی api‌ها پاک شده و در سمت کاربر هیچ api ای مشاهده نمیشود.

در صورت نیاز میتوان مشخص کرد کدام نوع api هارا نشان ندهد؛ به عنوان مثال Post و Put را نشان ندهد :

public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
{
    if (!httpContextAccessor.HttpContext.User.Identity.IsAuthenticated)
    {
        foreach (var item in swaggerDoc.Paths)
        {
            item.Value.Post = null;
            item.Value.Put = null;
        }
    }
}

در ادامه برای ثبت سرویس‌ها در کلاس Startup  :

public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpContextAccessor();
    services.AddAuthorization();
    services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
        .AddCookie(options =>
        {
            options.AccessDeniedPath = "/Login";
            options.Cookie.HttpOnly = true;
            options.LoginPath = "/Login";
            options.LogoutPath = "/Login";
            options.ExpireTimeSpan = TimeSpan.FromDays(15);
            options.SlidingExpiration = true;
            options.Cookie.IsEssential = true;
            options.ReturnUrlParameter = "returnUrl";
        });
    services.AddMvc();
    services.AddSwagger();
}

و اضافه کردن میان افزار swagger : 

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseAuthentication();
    app.UseCookiePolicy();
    app.UseSwaggerAndUI();
    app.UseMvc();
}

کدهای این مقاله را میتوانید از گیت هاب دانلود کنید ;)

Powered by Froala Editor