چگونه نام رشته ای enumها را درswagger نمایش دهیم؟✔️

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

فهرست مقاله [نمایش]

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

برای افزایش خوانایی و درک بهتر مستندات، بهتر است به‌جای اعداد، نام رشته‌ای مقادیر enum (مثل Active یا Pending) نمایش داده شود. این کار باعث می‌شود هم توسعه‌دهندگان راحت‌تر با API کار کنند و هم مستندات شما حرفه‌ای‌تر و واضح‌تر به‌نظر برسد.

در این مقاله با روش ساده‌ای آشنا می‌شوید که به کمک آن می‌توان enumها را در Swagger به‌شکل خوانا و کاربرپسند نمایش داد.

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

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

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

enum 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 ها می شود.

Training enum datatype in swagger