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

اگر تا به امروز از swagger در برنامه های خود استفاده نکرده اید ابزار بسیار ارزشمندی رو از دست داده اید. فقط با چند خط کد میتوانیم swagger را به پروژه اضافه کنیم و ابزاری برای داکیومنت و تست api ها را داشته باشیم.اگر با نحوه استفاده از swagger آشنا نیستید میتوانید آموزش استفاده از Swagger در Asp.NetCore را در سایت باگتو مطالعه نمایید. پس از نصب swagger ui با لوگوی swagger و مواردی از این برند ساخته می شود که ممکن است این موضوع برای برخی از افراد و شرکت ها خوشایند نباشد. یک خبر خوب این است که swagger را در بسیاری از پلتفرم ها از جمله asp.net core می توانیم شخصی سازی کنیم.در این مقاله  امکانات جالب را برای سفارشی سازی کردن swagger در asp.net core را به شما کاربران باگتو ارائه می دهیم.

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

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

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

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

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

 ابزار swagger داکیومنت ها را از روی یک فایل json تولید و نمایش  میدهد. خود این فایل json هم بر اساس api های ما تولید می شود. به صورت پیش فرض این فایل در مسیر http://domain.com/swagger/v1/swagger.json ایجاد می شود. مسیر این فایل را نیز می توانیم تغییر بدهیم. برای تغییر مسیر فایل json باید در قسمت app.UseSwagger یک RouteTemplate ایجاد کنیم. و سپس در app.UseSwaggerUI  مقدار  SwaggerEndPoint را تغییر بدهیم.کدهای فایل StartUp.cs را به صورت زیر تغییر دهید.

            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");