Swagger چیست؟ ابزار مستندسازی API با رابط کاربری زیبا

سواگر (Swagger) یکی از محبوب ترین ابزار برای توسعه دهندگان برای مستندسازی REST API است. شرکت هایی مانند گوگل، مایکروسافت و نتفلیکس از چارچوب Swagger استفاده می کنند. در این مقاله، برخی از اجزای شگفت انگیزی که Swagger ارائه می دهد و چرا آنها را توصیه می کنیم را بررسی می کنیم.

اگر نرم افزار، اپلیکیشن یا وب سایتی را توسعه می دهید، به احتمال زیاد در حال یکپارچه سازی API ها هستید. در دنیای توسعه امروزی، چرخه عمر توسعه نرم افزار به APIها بستگی دارد. API ها (واسط های برنامه نویسی کاربردی) توسعه دهندگان را به هم متصل می کنند و داده ها و توسعه با ارزش را به اشتراک می گذارند. آنها به شرکت ها اجازه می دهند تا داده ها و عملکرد خود را برای استفاده در معرض دید عموم قرار دهند. سپس می توانیم آن داده ها را به برنامه هایی که می سازیم اضافه کنیم.

به عنوان مثال، اگر می خواهید برنامه ای ایجاد کنید که به کاربران کمک کند رستوران های محبوب منطقه خود را پیدا کنند، نیازی به ساخت آن از ابتدا نیست. شما به سادگی می توانید Yelp API را در برنامه خود ادغام کنید. اما، برای اینکه توسعه دهندگان محتوای API خود را به اشتراک بگذارند، به پروتکل ها یا اسناد واضحی نیاز دارند که دیگران بتوانند از آن پیروی کنند. اینجا جایی است که سواگر در آن جای می گیرد.

Swagger چگونه کار می کند؟

قبل از ورود به Swagger، اجازه دهید مروری کوتاه بر مستندات API و مشخصات OpenAPI در ارتباط با Swagger داشته باشیم.

مروری بر داکیومنت API

یک API به عنوان واسطه بین یک برنامه کاربردی و وب سروری عمل می کند که می خواهند برای اشتراک گذاری اطلاعات با یکدیگر ارتباط برقرار کنند. ارتباطات گسترده در پشت صحنه در جریان است، بنابراین، مستندسازی خوب API های شما برای اطمینان از تجربه مثبت توسعه دهنده ضروری است.

مستندات API مانند یک کتابچه راهنمای مرجع است که حاوی دستورالعمل هایی در مورد نحوه استفاده موثر و یکپارچه سازی با یک API است. داشتن یک محصول عالی برای ارائه چه فایده ای دارد، اگر کسی نحوه استفاده از آن را نمی داند؟ به همین دلیل است که داکیومنت ها ارزشمند هستند. اما، چه چیزی را باید در داکیومنت های API لحاظ کنید؟

داکیومنت های API باید شامل (اما نه محدود به) موارد زیر باشد:

مروری بر API و مشکلی که در حال حل آن است
آموزش و مثال همراه با راهنمای گام به گام
واژه نامه ای که اصطلاحات مختلف را توضیح می دهد
عملیاتی که نقطه پایانی از آنها پشتیبانی می کند
پاسخی که یک API از یک درخواست برمی‌گرداند

نمای کلی مشخصات OpenAPI

مشخصات OpenAPI (که قبلاً به عنوان مشخصات Swagger شناخته می شد) یک قالب استاندارد برای API های REST را توصیف می کند. این استاندارد از این جهت مهم است که همه کسانی که API های REST را می نویسند با بهترین شیوه های آن مانند نسخه سازی، ایمنی و مدیریت خطا مطابقت داشته باشند. می توانیم بگوییم که OpenAPI شبیه یک الگو با مجموعه ای از قوانین و محدودیت ها است که توضیح می دهد چگونه می توانید یک API را توصیف کنید. معمولاً در قالب فایل YAML یا JSON نوشته می شود و برای انسان و ماشین قابل خواندن است.

Swagger چیست؟

اگر یک API از ابتدا ساخته اید، احتمالاً این سوال برای شما پیش آمده است که آیا تمام اطلاعات لازمی که کاربر برای موفقیت به آن نیاز دارد را وارد کرده اید یا خیر. Swagger با اجرای مشخصات OpenAPI برای اطمینان از رعایت دستورالعمل‌ها، زمان زیادی را در نوشتن اسناد API صرفه‌جویی می‌کند.

بیایید با درست کردن برخی اصطلاحات شروع کنیم. از آنجا که مشخصات OpenAPI در ابتدا SwaggerAPI نامیده می شد، گاهی اوقات مردم هنوز هم مشخصات OpenAPI را به عنوان Swagger می گویند. در سراسر این مقاله، وقتی می‌گوییم Swagger، به مجموعه‌ای از ابزارهای تولید شده برای کمک به طراحی، ساخت و مستندسازی APIها با استفاده از مشخصات OpenAPI اشاره می‌کنیم.

مشخصات Swagger قبلاً به عنوان مشخصات OpenAPI شناخته می شد. تفاوت اکنون این است که OpenAPI دستورالعمل یا "اسکیما" است و Swagger اجرای آن دستورالعمل ها است. بنابراین، Swagger ابزارهایی را برای پیاده سازی مشخصات OpenAPI فراهم می کند. مشخصات Swagger و OpenAPI ساختار REST API را توصیف می کند تا ماشین ها بتوانند آنها را بخوانند و ماک کنند. به لطف اتوماسیون‌های OpenAPI و Swagger، فرآیند مستندسازی API برای توسعه‌دهندگان بسیار آسان‌تر است تا تولید و نگهداری کنند.

برای بررسی تجربه کاربری UX در API نویسی می توانید از این مقاله جهت کسب اطلاعات بیشتر استفاده کنید.

مزایای Swagger و یک محدودیت قابل توجه

بنابراین این پلتفرم قدرتمند:

خطاها را کاهش می دهد. مشخصات Swagger/OpenAPI می تواند به کاهش خطاها و ناهماهنگی ها در توسعه API کمک کند. با ارائه یک تعریف واضح و ثابت از یک API، درک و پیاده سازی صحیح API آسان تر است.
تست را ساده می کند. Swagger یک رابط کاربر پسند برای کاوش و تست API ها ارائه می دهد. این می تواند به توسعه دهندگان کمک کند تا به سرعت API های خود را تست و تأیید کنند و زمان و تلاش مورد نیاز برای آزمایش را کاهش دهند.

همکاری را تسهیل می کند. با ارائه یک زبان و قالب مشترک برای توصیف APIها، Swagger می تواند همکاری بین اعضای تیم، از جمله توسعه دهندگان، تست کنندگان و نویسندگان فنی را آسان کند. این می تواند به بهبود ارتباطات و کاهش سوء تفاهم کمک کند.

تعمیر و نگهداری را بهبود می بخشد. اسناد API ایجاد شده در Swagger می تواند به بهبود قابلیت نگهداری APIها کمک کند. با ارائه یک توضیح واضح و به روز از API، نگهداری و به روز رسانی API ها در طول زمان برای توسعه دهندگان آسان تر می شود.

نظارت API را فعال می کند. در دسترس بودن، سرعت و عملکرد API را از تعریف OpenAPI خود نظارت کنید. این رویکرد می تواند به شناسایی و حل مسائل قبل از تبدیل شدن به مشکلات اساسی کمک کند.

یک رابط کاربری منظم ارائه می دهد. Swagger رابط کاربر پسندی را برای کاوش و آزمایش API ها فراهم می کند که می تواند به بهبود کیفیت کلی اسناد API کمک کند.

قابلیت نسخه بندی. نسخه سازی به توسعه دهندگان اجازه می دهد تا چندین نسخه از یک API را در طول زمان حفظ کنند. این ویژگی می تواند به اطمینان از سازگاری با عقب و کاهش خطر شکستن تغییرات کمک کند.

ادغام ها را فراهم می کند. Swagger را می توان با ابزارها و چارچوب های مختلف دیگری مانند Postman، Jenkins و Docker ادغام کرد که می تواند به ساده سازی توسعه و استقرار API ها کمک کند.

همانطور که می بینید، Swagger مزایای زیادی در مورد موارد استفاده مختلف دارد. با این حال، نویسندگان فنی نه تنها اسناد API بلکه پایگاه های دانش را نیز ایجاد می کنند. این بدان معناست که استفاده از Swagger برای نوشتن فنی کامل کافی نیست، اما ما چیزی برای ارائه داریم.

برخی از مشکلات و چالش های رایج استفاده از Swagger یا OpenAPI برای مشخصات API چیست؟

هیج ابزاری بدون عیب و نقض نیست و هر کدام همراه با ویژگی های مثبتی که دارند، یک سری چالش ها و مشکلات نیز در آن ها وجود دارد که ما می خواهیم این چالش ها را مورد بررسی قرار دهیم.

1. سینتکس و خطاهای اعتبار سنجی

یکی از رایج ترین و خسته کننده ترین مشکلاتی که ممکن است هنگام استفاده از Swagger یا OpenAPI با آن مواجه شوید، خطاهای سینتکس و اعتبارسنجی است. این خطاها ممکن است هنگام نوشتن یا ویرایش مشخصات API خود در فرمت YAML یا JSON رخ دهند و می توانند از تجزیه یا رندر صحیح مشخصات شما جلوگیری کنند. خطاهای سینتکس ممکن است به دلیل وجود نویسه‌های گم شده یا اضافی، مشکلات تورفتگی یا انواع داده‌های نادرست باشد. خطاهای اعتبار سنجی می تواند با نقض قوانین یا محدودیت های مشخصات Swagger یا OpenAPI، مانند استفاده از مقادیر، پارامترها یا مراجع نامعتبر ایجاد شود. برای جلوگیری یا رفع این خطاها، باید از یک ویرایشگر کد استفاده کنید که از برجسته‌سازی سینتکس و تکمیل خودکار پشتیبانی می‌کند، و یک ابزار اعتبارسنجی که می‌تواند مشخصات شما را برای مطابقت بررسی کند و هرگونه خطا یا هشدار را گزارش کند.

2. مسائل مربوط به نسخه و سازگاری

یکی دیگر از چالش‌های رایجی که ممکن است هنگام استفاده از Swagger یا OpenAPI با آن مواجه شوید، مشکلات نسخه‌سازی و سازگاری است. این مشکلات ممکن است زمانی به وجود بیایند که باید مشخصات API خود را به‌روزرسانی یا تغییر دهید تا تغییرات در عملکرد، طراحی یا الزامات API شما منعکس شود. مسائل مربوط به نسخه و سازگاری می‌تواند بر نحوه تعامل مشخصات API شما با ابزارها یا پلتفرم‌های دیگر، مانند تولیدکننده‌های کد، تولیدکنندگان اسناد، ابزارهای تست یا کتابخانه‌های سرویس گیرنده تأثیر بگذارد. برای مثال، اگر از نسخه قدیمی Swagger یا OpenAPI استفاده می‌کنید، ممکن است نتوانید از برخی از ویژگی‌ها یا برنامه‌های افزودنی جدیدتر که توسط آخرین نسخه پشتیبانی می‌شوند استفاده کنید. یا اگر از نسخه جدیدتر Swagger یا OpenAPI استفاده می کنید، ممکن است با برخی از ابزارها یا پلتفرم های قدیمی که بر اساس نسخه قبلی هستند با مشکلات سازگاری مواجه شوید. برای جلوگیری یا حل این مشکلات، باید بهترین روش‌ها را برای نسخه‌سازی API، مانند استفاده از نسخه‌سازی معنایی، حفظ سازگاری به عقب، و مستندسازی تغییرات و منسوخ‌ها دنبال کنید.

3 مسائل پیچیدگی و تعمیر و نگهداری

سومین مشکل رایجی که ممکن است هنگام استفاده از Swagger یا OpenAPI با آن مواجه شوید، پیچیدگی و مسائل مربوط به نگهداری است. این مشکلات زمانی رخ می دهد که مشخصات API شما بسیار بزرگ، پیچیده یا برای مدیریت دشوار شود. مشکلات پیچیدگی و تعمیر و نگهداری می تواند بر خوانایی، قابلیت استفاده و کیفیت مشخصات API شما تأثیر بگذارد و می تواند به روز نگه داشتن آن و مطابقت با اجرای API شما را دشوارتر کند. به عنوان مثال، اگر از تعاریف درون خطی، مراجع یا پسوندهای سفارشی زیادی در مشخصات API خود استفاده می‌کنید، ممکن است با یک سند طولانی، درهم و برهم یا اضافی مواجه شوید که پیمایش یا ویرایش آن دشوار است. یا اگر از فایل‌های خارجی، ماژول‌ها یا افزونه‌های زیادی در مشخصات API خود استفاده می‌کنید، ممکن است با سندی تکه‌تکه، ناسازگار یا وابسته مواجه شوید که نگهداری یا ادغام آن سخت است. برای جلوگیری یا کاهش این مشکلات، باید از یک رویکرد ماژولار، قابل استفاده مجدد و مختصر برای نوشتن مشخصات API خود استفاده کنید و از ابزارهایی استفاده کنید که می توانند به شما در سازماندهی، ساده سازی و خودکارسازی گردش کار مشخصات API خود کمک کنند.

4. مسائل امنیتی و حریم خصوصی

چهارمین چالش رایجی که ممکن است هنگام استفاده از Swagger یا OpenAPI با آن مواجه شوید، مسائل امنیتی و حریم خصوصی است. این مشکلات ممکن است زمانی ایجاد شوند که شما نیاز به محافظت از مشخصات API خود در برابر دسترسی، تغییر یا افشای غیرمجاز داشته باشید. مسائل امنیتی و حریم خصوصی می‌توانند بر یکپارچگی، محرمانه بودن و در دسترس بودن مشخصات API شما تأثیر بگذارند و می‌توانند API شما را در معرض خطرات یا تهدیدات احتمالی قرار دهند. برای مثال، اگر از اطلاعات حساس یا محرمانه در مشخصات API خود استفاده می‌کنید، مانند اعتبارنامه‌های احراز هویت، کلیدهای API یا داده‌های شخصی، ممکن است امنیت یا حریم خصوصی API یا کاربران خود را به خطر بیندازید. یا اگر از ابزارها یا پلتفرم های عمومی یا ناامن برای ایجاد، ذخیره یا اشتراک گذاری مشخصات API خود استفاده می کنید، ممکن است مشخصات API خود را در معرض حملات مخرب یا نقض داده ها قرار دهید. برای جلوگیری یا کاهش این مشکلات، باید از روش‌های ایمن و رمزگذاری‌شده برای مدیریت، انتقال و ذخیره مشخصات API خود استفاده کنید و از ابزارهایی استفاده کنید که می‌توانند به شما در اجرای سیاست‌ها و استانداردهای امنیتی و حریم خصوصی برای مشخصات API خود کمک کنند.

5. مسائل ارتباطی و همکاری

پنجمین چالش رایجی که ممکن است هنگام استفاده از Swagger یا OpenAPI با آن مواجه شوید، مشکلات ارتباطی و همکاری است. این مشکلات زمانی رخ می دهد که شما نیاز به برقراری ارتباط یا همکاری با سایر ذینفعان یا تیم های دخیل در توسعه یا مصرف API خود دارید. مسائل ارتباطی و همکاری می تواند بر همسویی، بازخورد و کیفیت مشخصات API شما تأثیر بگذارد و می تواند منجر به سوء تفاهم، درگیری یا خطا شود. به عنوان مثال، اگر از ابزارها یا قالب‌های مختلف برای ایجاد یا مصرف مشخصات API خود استفاده می‌کنید، ممکن است با مشکلات همکاری یا سازگاری با سایر ذینفعان یا تیم‌ها مواجه شوید. یا اگر در مشخصات API خود از اصطلاحات، توصیف‌ها یا مثال‌های نامشخص یا متناقض استفاده می‌کنید، ممکن است سایر ذینفعان یا تیم‌ها را گیج یا گمراه کنید. برای جلوگیری یا غلبه بر این مشکلات، باید از ابزارها یا قالب‌های استاندارد و متداول برای ایجاد یا مصرف مشخصات API خود استفاده کنید و از ابزارهایی استفاده کنید که می‌توانند به شما در مستندسازی، نظر دادن، بررسی و اشتراک‌گذاری مشخصات API خود با سایر ذینفعان یا تیم‌ها کمک کنند.

مثال‌ها و ویژگی‌های Swagger API

SwaggerHub یک ابزار مستندسازی API آنلاین است که برای ساده سازی و تسریع داکیومنت API طراحی شده است. Swaggerhub بر روی یک زبان توصیف API متمرکز است. بیایید ویژگی‌های بسیاری از هر مؤلفه Swagger را مرور کنیم: ویرایشگر Swagger، Swagger UI، و Swagger Codegen.

ویرایشگر Swagger

Swagger Editor یک ویرایشگر مبتنی بر مرورگر است که در آن می توانید اسناد API و مشخصات OpenAPI را بنویسید و ویرایش کنید. می توانید از ویرایشگر Swagger از طریق مرورگر استفاده کنید، دانلود کنید تا به صورت محلی اجرا شود یا از نسخه میزبان مانند SwaggerHub استفاده کنید. در زیر، برخی از ویژگی های کلیدی ویرایشگر را فهرست کرده ایم.

پنل کاربر پسند
Swagger Editor یک ویرایشگر در پنل سمت چپ دارد که می‌توانید تمام درخواست‌ها و داده‌های پاسخ خود را در آن وصل کنید. ویرایشگر از فرمت YAML یا JSON پشتیبانی می کند. در پنل سمت راست، می توانید مستندات را همانطور که کاربر نهایی می بیند، مشاهده کنید.

گزارش خطای زنده
اگر خطایی دارید، گزارش خطای زنده ردیفی را که باید تنظیم کنید تا با مشخصات مطابقت داشته باشید به اشتراک می گذارد.

گزینه تکمیل خودکار
اگر ترجیح می دهید هر بار که یک متد جدید GET دارید بازنویسی نکنید، می توانید از گزینه تکمیل خودکار برای ساخت اسناد خود با سرعت بیشتری استفاده کنید.

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

آنچه ما دوست داریم:
ویرایشگر Swagger این امکان را برای ما فراهم می کند که مشخصات خود را قبل از ورود به کدنویسی طراحی کنیم. ویرایشگر دقیقاً به ما می‌گوید که API چه چیزی را درخواست می‌کند، درخواست چگونه خواهد بود و چه پاسخی می‌توانیم انتظار داشته باشیم. به این ترتیب، ما قبلاً یک الگو برای دنبال کردن داریم که می تواند به کاهش خطاها و زمان کلی کدنویسی کمک کند.

Swagger UI

اکنون که اسناد خود را با ویرایشگر خود ایجاد کرده ایم، به راهی برای به اشتراک گذاشتن آن با کاربران خود نیاز داریم. Swagger UI مشخصات OpenAPI را به عنوان اسناد API تعاملی نمایش می دهد. این فایل YAML را می گیرد و آن را به یک سند رو به روی کاربر تبدیل می کند که به کاربران شما امکان می دهد تماس های API را مستقیماً در مرورگر امتحان کنند. برخی از ویژگی های کلیدی عبارتند از:

به راحتی یکپارچه شده است
Swagger UI به راحتی با برنامه های موجود و جدید ادغام می شود.

راه اندازی انعطاف پذیر
Swagger UI می تواند به روش های مختلفی مانند ابر، لوکال، بپکیج های node و غیره اجرا شود.

در ارتباط بودن
Swagger UI دارای دکمه "try it out" است که پارامترهای کوئری را به فیلد تبدیل می کند. این به شما امکان می دهد تا با یک API واقعی در ارتباط باشید.

آنچه ما دوست داریم:
با استفاده از Swagger UI برای نمایش اسناد API خود، می توانیم در زمان قابل توجهی صرفه جویی کنیم. همچنین به کاربران این امکان را می‌دهد که بدون زحمت با هم تعامل داشته باشند و هر عملیاتی را که API ما در معرض دید قرار می‌دهد برای مصرف آسان امتحان کنند.

Swagger Codegen

تا کنون، ما مستندات API تعاملی را با Swagger Editor و Swagger UI ایجاد کرده‌ایم، اکنون زمان اجرای منطق سرور است تا API ما بتواند فعال شود. Swagger Codegen خرد سرور، SDK های کلاینت و کتابخانه های کلاینت را از مشخصات OpenAPI تولید می کند. Swagger Codegen دارای ویژگی های زیر است:

ایجاد سرور
Swagger Codegen انتخاب های زیادی از سرورها/فریمورک ها مانند سرور Go، سرور لاراول، سرور Scala و سرور Node را در اختیار شما قرار می دهد. شما می توانید سروری را انتخاب کنید که از پیاده سازی Backend شما پشتیبانی می کند.

SDK های سمت کلاینت
شما می توانید به سرعت و به راحتی SDK های کلاینت را برای API ها به زبان هایی مانند جاوا اسکریپت، لاراول، PHP و غیره بسازید. یک SDK کلاینت شامل کلاس های بسته بندی است که می توانید از آنها برای فراخوانی API از برنامه خود بدون نیاز به پاسخگویی به درخواست ها و پاسخ های HTTP استفاده کنید.

آنچه ما دوست داریم:
Swagger Codegen فرآیند ساخت شما را ساده می کند تا تیم شما بهتر بر روی پیاده سازی و پذیرش API شما تمرکز کند.

چه کسی می تواند از Swagger سود ببرد؟

تعاریف OpenAPI اسناد متنی ساده ای هستند که می توانند در هر نوع مخزنی مانند GitHub نگهداری شوند، به این معنی که می توان روی آنها در یک محیط مشترک کار کرد.

اگر سرعت و قابلیت اطمینان برای پروژه شما مهم است، ایجاد API خود در Swagger Editor به این معنی است که توسعه دهندگان شما به گزینه های تکمیل خودکار و گزارش های خطای زنده دسترسی خواهند داشت تا با مشخصات مطابقت داشته باشند. و استفاده از codegen به شما امکان می دهد از کد خودکار Swagger برای SDK ها استفاده کنید.

اسناد API یا API در دسترس ندارید، اما مشتریان/شریک‌های شما درخواست دارند. می‌توانید از Swagger Editor برای طراحی یک API و نمایش نقاط پایانی با استفاده از یک سرور ساختگی، قبل از اجرای آن در محصول خود استفاده کنید.

یک API فقط به اندازه مستنداتش خوب است، به هر حال، ما نمی‌توانیم از APIها استفاده کنیم، اگر توضیحاتی وجود نداشته باشد، ناقص باشد یا استفاده از آن دشوار باشد. Swagger UI به شما امکان می دهد اسناد را به راحتی از روی کد تولید کنید.

بهترین شیوه های مستندسازی Swagger API

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

مطمئن شوید که از اصطلاحات و لحن صدای ثابتی استفاده می‌کنید، این یک رمان نیست، بنابراین نیازی نیست مدام به روش‌های جدیدی برای بیان خود فکر کنید. اگر باید از اصطلاحات فنی، کلمات اختصاری و/یا اختصارات استفاده کنید، مطمئن شوید که استانداردهای صنعتی و به طور گسترده قابل درک هستند، و در صورت لزوم آنها را در یک واژه نامه توضیح دهید. در نهایت، مطمئن شوید که اسناد شما به روز نگه داشته می شوند. اسناد منسوخ می تواند گمراه کننده، وقت گیر و به طور بالقوه برای کاربران نهایی مضر باشد.

Swagger یا Postman کدام بهتر است؟

انتخاب بین Swagger و Postman بستگی به نیازهای خاص شما و مرحله چرخه عمر توسعه API دارد که روی آن متمرکز هستید. اگر هدف اصلی شما طراحی، مستندسازی و اطمینان از سازگاری API است، Swagger یک انتخاب عالی است. Swagger در ارائه یک روش استاندارد و قابل خواندن توسط ماشین برای تعریف و توصیف APIها با استفاده از مشخصات OpenAPI برتر است. همکاری بین تیم ها را تقویت می کند، بهترین شیوه های طراحی API را اعمال می کند و اسناد تعاملی را از طریق Swagger UI ارائه می دهد.

با این حال، اگر تاکید شما بر تست API، اتوماسیون و نظارت است، Postman می درخشد. Postman تست API را ساده می کند، از گردش کار تست خودکار پشتیبانی می کند و ویژگی هایی مانند مجموعه ها و مانیتورها را برای آزمایش و نظارت مستمر ارائه می دهد.

ما در مقاله سواگر در مقابل Postman به صورت کامل تفاوت ها و نکات کلیدی هر دو را بررسی کردیم.

نحوه نصب سواگر

روش های مختلفی برای نصب سواگر وجود دارد که می توانید در وبسایت رسمی سواگر به آن دسترسی پیدا کنید. ما در این جا با npm و داکر به نحوه نصب Swagger خواهیم پرداخت.

NPM

سه ماژول برای npm منتشر شده است: swagger-ui، swagger-ui-dist و swagger-ui-react.

swagger-ui برای پروژه‌های وب جاوا اسکریپت که شامل باندلر های ماژول، مانند Webpack، Vite و Rollup هستند، در نظر گرفته شده است. فایل اصلی آن تابع اصلی Swagger UI را صادر می کند، و ماژول همچنین شامل یک فایل استایل با فاصله نام در swagger-ui/dist/swagger-ui.css است.

در اینجا یک مثال است:

import SwaggerUI from 'swagger-ui'
// or use require if you prefer
const SwaggerUI = require('swagger-ui')
SwaggerUI({
  dom_id: '#myDomId'
})

در مقابل، swagger-ui-dist برای پروژه‌های سمت سرور است که برای ارائه خدمات به کلاینت به دارایی نیاز دارند. این ماژول، زمانی که وارد می شود، شامل یک تابع helper absolutePath است که مسیر فایل سیستم مطلق را به جایی که ماژول swagger-ui-dist نصب شده است، برمی گرداند.

داکر

می توانید یک تصویر داکر از پیش ساخته شده از Swagger-ui را مستقیماً از Docker Hub بکشید:

docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui

nginx با Swagger UI در پورت 80 شروع می شود.

یا می توانید swagger.json خود را در هاست خود ارائه دهید:

docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

همچنین می‌توانید یک URL به swagger.json در یک میزبان خارجی ارائه دهید:

docker run -p 80:8080 -e SWAGGER_JSON_URL=https://petstore3.swagger.io/api/v3/openapi.json swaggerapi/swagger-ui

برای آشنایی با نحوه نوشتن API تمیز و خوب این مقاله را بررسی کنید.

نتیجه

نوشتن اسناد API در Swagger مقدار حجم کار مستندات را خودکار می‌کند و تا حدی کارها را برای توسعه دهنده گان ساده‌تر می‌کند، اما یادآوری برخی از جنبه‌های کلیدی آن مهم است. مانند برنامه ریزی مستندات خود قبل از شروع نوشتن، به یاد داشته باشید که برای چه کسی می نویسید و مطمئن شوید که مستندات به روز هستند.

مشخصات OpenAPI و Swagger برای سال‌ها به صورت مترادف مورد استفاده قرار می‌گرفتند، همان‌طور که در ابتدا مشخصات API Swagger بود، اما از زمانی که مشخصات به OpenAPI تبدیل شد، Swagger دیگر تنها راه‌حل مستندسازی API برای OpenAPI نیست. اکنون ابزارهای بیشتری در دسترس هستند، و به عنوان بخشی از برنامه ریزی خود، باید در نظر بگیرید که آیا ابزارهای دیگر نیز مناسب تر هستند یا خیر. اگر هنوز یک ابزار مدیریتی برای اسناد API خود مانند Swagger قرار نداده‌اید، حتماً باید این کار را در نظر بگیرید.

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