آموزش شخصی سازی swagger در asp.net core

اگر تاکنون از Swagger در پروژه‌های ASP.NET Core خود استفاده نکرده‌اید، یکی از قدرتمندترین ابزارهای مستندسازی و تست API را نادیده گرفته‌اید. تنها با چند خط کد می‌توان Swagger را به پروژه اضافه کرد و به‌سادگی مستنداتی تعاملی و قابل تست برای APIها در اختیار داشت.

در سایت باگتو، مقاله‌ی «مستندسازی خودکار APIها با Swagger در ASP.NET Core» راهنمایی کامل برای شروع استفاده از این ابزار است. با این حال، پس از نصب Swagger UI، ممکن است ظاهر پیش‌فرض آن و لوگوی برند Swagger برای برخی شرکت‌ها یا پروژه‌های رسمی مناسب نباشد. خبر خوب اینجاست: Swagger در ASP.NET Core کاملاً قابل سفارشی‌سازی است.

در این مقاله قصد داریم روش‌های حرفه‌ای و کاربردی برای شخصی‌سازی ظاهر و رفتار Swagger UI را با شما به اشتراک بگذاریم؛ از تغییر عنوان صفحه گرفته تا افزودن استایل اختصاصی و حذف عناصر پیش‌فرض برندینگ.

تغییر مسیر نمایش داکیومنتswagger

به صورت پیش فرض Swwager Ui در صفحه http:domain.com/swagger بارگیری می شود. اگر می خواهید این مسیر را تغییر دهید باید گزینه ی RoutePrefix را به متد UserSwaggerUi در StatrUp.cs اضافه کنیم.

public void Configure(...)  
{
    ...

    app.UseSwaggerUI(c =>
    {
        c.RoutePrefix = "docs";
    });
}

همانطور که در تصویر می بیند آدرس بارگذاری داکیومنت تغییر کرد به آنچه که ما وارد RoutePrefix کردیم.

            app.UseSwagger(c =>
            {
                c.RouteTemplate = "docs/{documentName}/docs.json";
            });

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

تغییر style صفحه داکیومنت swagger

رابط کاربری پیش فرض swagger ui خیلی خوب طراحی شده  است، اما ممکن است بخواهیم از لوگو و رنگ سازمانی خودمان استفاده کنیم. خوشبختانه تیم swagger این امکان را در اختیار ما قرار داده است و ما می توانیم ui اختصاصی خودمان را طراحی و استفاده کنیم.

قبل از هر کاری باید میان افزاری برای پشتیبانی از فایل های استاتیک به پروژه اضافه کنیم.

            app.UseStaticFiles();

سپس در قسمت app.UseSwaggerUi  کد زیر را اضافه می کنیم. این خط کد فایل css اختصاصی خودمان را که طراحی کرده ایم به swagger اینجکت می کند.

c.InjectStylesheet("/swagger-ui/custom.css");  

اگر در پروژه خود قسمت wwwroot را نمی بینید یه پوشه با این نام ایجاد کنید.

سپس در داخل wwwroot  یک پوشه به نام swagger-ui ایجاد و در داخل پوشه یه فایل css به نام custom.css ایجاد کنیدو کدهای زیر را در آن بنویسید.

.swagger-ui .topbar {
    background-color: grey;
    border-bottom: 3px solid black;
}

.swagger-ui .opblock-tag-section {
    background-color: dimgrey;
  
}

پس از اعمال تغییرات ظاهر swagger به صورت زیر تغییر می کند. شما می توانید تمامی استایل های swagger را تغییر دهید.

تغییر favicon در swagger

برای تغییر favicon در swagger باید فایل های icon را wwwroot قرار دهیم. محل قرارگیری این تصاویر به مسیری دارد که ما برای swagger ui در بخش اول همین مقاله تعیین کرده ایم بستگی دارد. در اینجا ما مسیر نمایش داکیومنت را docs قرار داده ایم، بر این اساس باید در پوشه wwwroot یک پوشه به نام docs ایجاد کنیم و سپس سه فایل با نام های favicon.ico , favicon-16x16.png , favicon-32x32.png در این مسیر  قرار دهیم.

برنامه را اجرا کنید و با فشردن دکمه های ctrl+f5  صفحه را بروزرسانی کنید تا تغییرات را ببینید. اگر تصاویر تغییر نکردند ممکن است فراموش کرده باشید میان افزار app.UseStaticFiles() را به Configure اضافه کرده باشید.

تغییر لوگوی Swagger

 برای تغییر لوگوی swagger در همان فایل custom.css که ایجاد کردیم کد زیر را وارد نمایید تا لوگوی شما جایگزین شود.

img {
    letter-spacing: -1000em;
    width: 150px;
    height: 50px;
    content: url(https://bugeto.net/images/Icon/LogoSefid.png);
}

البته برای انجام این کار روش های دیگری از جمله استفاده از jquery وجود دارد که می توانید از آنها هم استفاده کنید.

روش افزودن jquery شخصی به swagger همانند افزودن فایل css است. برای انجام این کار یک فایل jquery با نام custom.js در پوشه swagger-ui ایجاد می کنیم و کد زیر را به app.UseSwaggserUi اضافه میکنیم.

 c.InjectJavascript("/swagger-ui/custom.js");