نمایش نام رشته ای enum ها در swagger

همانطور که می دانید وقتی از نوع شمارشی یا همان enum در dto های ورودی یک api استفاده می کنیم، ابزار swagger  آنها را به صورت عددی نمایش می دهد و کسانی که از api های ما  می خواهند استفاده کنند کمی سردرگم می شوند چون اعداد هیچ مفهومی ندارند و این یک ضعف برای داکیومنت ما محسوب می شود. بهتر است بجای اعداد نام رشته ای مقادیر enum را نمایش دهیم که کاربران استفاده کننده راحتر مفهوم داده های ورودی را درک کنند.

فرض کنید ما نوع داده ای enum زیر را به عنوان ورودی می خواهیم از کاربر دریافت کنیم.

    public enum Priority
    {
        Much = 1,
        medium = 2,
        Low = 3,
    }

تصویر زیر حالت پیش فرض استفاده از نوع های شمارشی در  swagger را نشان می دهد. همانطور که مشاهده می کنید در کادر ورود اطلاعات پارامتر های api ما مقادر 1,2,3 را برای پارامتر Priority می توانیم انتخاب کنیم.

برای فعال سازی نمایش نام رشته ای نوع های شمارشی (enum) در swagger  کد زیر را به AddSwaggerGen اضافه می کنیم.

                c.DescribeAllEnumsAsStrings();

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

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "Training enum datatype in swagger with bugeto", Version = "v1" });
                c.DescribeAllEnumsAsStrings();
            });

حالا اگر پروژه asp.net core  را اجرا کنیم و صفحه swagger را باز کنیم می بینیم که به جای اعداد از نام رشته ای مقادری enum استفاده شده است که این کار باعث افزایش بهره وری استفاده کنندگان از  api  ها می شود.

امیدوارم این آموزش برای شما مفید بوده باشد.

درضمن مقاله مستند سازی خودکار api ها در asp.net core با استفاده از swagger را نیز می توانید در بلاگ باگتو مطالعه نمایید.