سلام، امین علیزاده هستم برنامه نویس تیم iFNo. امروز قراره یکم راجب Swagger و OpenAPI براتون بنویسم سعی میکنم به زبان ساده باشه و در آخر مثالی از نحوه‌ی پیاده سازی رو برای شما شرح میدم. امیدوارم مفید باشد.
سواگر ( Swagger ) یک ابزار متن باز ( Open Source ) و بسیار قدرتمند ( اما خیلی ساده! ) هستش که برای طراحی و مستندسازی تا تست و آماده سازی محصول برای استفاده‌ی کاربران ( Deployment )، استفاده میشود. اگر شما از معماری RESTful API برای توسعه سرویس هاتون استفاده می‌کنید حتما تا آخر این مطلب همراه من باشید.
پروژه ای که جدیدا استارتش رو زدیم قراره کلی سرویس به دردبخور برای کسب و کارها و اپلیکیشن ها ( به خصوص استارت‌آپ ها ) ارائه بده ( Serverless ). ما می‌خواهیم توسعه دهنگان این کسب و کارها خیلی راحت بتوانند با سرویس های ما ارتباط برقرار کنند برای همین نیاز داریم یک مستند سازی واضح و شفاف برای سرویس‌هایی که توسعه می دهیم داشته باشیم. تا توسعه دهنده خیلی گیج نشه که دقیقا چطوری باید API های ما رو Call کنه ( دقیقا مثل Documentation درگاه های پرداخت ایرانی که معلوم نیست چی نوشتن توش ? )
پس نیاز داریم یک ابزار قوی برای مدیریت، مستندسازی ( Documentation APIs ) و حتی تست APIهای سرویس ها داشته باشیم برای همین Swagger رو انتخاب کردیم :)
در حقیقت Swagger یک زبان توصیف رابط ( Interface Description Language ) هستش که توسط یک فایل JSON یا YAML طراحی و نوشته میشه یعنی به طور ساده یک واسط بین Server و Client هستش که ارتباطات بین این دو را برای شما راحت میکنه مثلا در یک تیم برنامه نویسی یکی از مشکلات کسایی که بخش بک اند رو توسعه میدن توضیح دادن APIها به فرانت اند کارهاست ? با swagger می‌تونید بیشتر زمان و تمرکزتون رو بزارید رو بیزینس لاجیکتون چون یک Documentation خیلی کامل برای شما به صورت کاملا اتوماتیک ایجاد میکنه ( در اکثر زبان های برنامه نویسی ) و شما نیازی نیست وقتتون رو صرف نوشتن داکیومنت کنید.
قبل از ادامه بیایید مفهموم OpenAPI Specification رو بررسی کنیم. با توجه به اینکه جهان داره میره به سمت اپلیکیشن های سرویس بیس و معماری میکروسرویس، لازم هست که برنامه نویس‌ها یک رابط استاندارد برای APIهای RESTful خودشون داشته باشند. اینجاست که مفهوم OpenAPI مطرح میشود. OpenAPI Specification یک فرمت متن باز ( Open Source ) است برای ایجاد فایل‌های رابط که قابل خواندن توسط ماشین و قابل درک برای انسان می باشد. یعنی یک استاندارد جهانی برای تولید و توصیف و بصری سازی ( visualizing ) APIهای وب سرویس های RESTful شما. این فایل ها موارد ضروری برای استفاده از APIهای وب سرویس شما را مشخص میکنند از جمله:
درنهایت مزیت اصلی استفاده از تعریف استاندارد این است که کاربران شخص ثالث می توانند با حداقل منطق پیاده سازی با خدمات تعامل داشته باشند و آن را درک کنند ، به شرطی که با اصول اولیه RESTful API آشنا باشند.
شاید الان به این فکر کنید Swagger و OpenAPI چه فرقی باهم دارند آیا اصلا متفاوت هستند ؟!
اگر دقت کنید هرجا که اسم OpenAPI میاد Swagger هم مطرح میشه اما باید بدونید این دو کلا دارای مفهوم متفاوتی هستند از نظرعملکرد!
همانطور که گفته شده OpenAPI Specification یک استاندارد جهانی برای تولید و توصیف و بصری سازی ( visualizing ) APIهای وب سرویس های RESTful شما می‌باشد که توسط شرکت های خیلی بزرگی مانند Microsoft, Google, Capital, Swagger و IBM ساخته شده است.
از طرفی Swagger شرکتی است که مجموعه نرم افزاری بسیار قوی از جمله ابزارهای منبع باز ، رایگان و تجاری برای پیاده سازی OpenAPI Specification توسعه داده است و از انجایی که یکی از شرکت های سازنده OpenAPI Specification هم هست در نتیجه اغلب اسم این شرکت همراه با OpenAPI Specification در بسیاری جاها مطرح شده در نتیجه شما لزومی نداره حتما از Swagger برای وب سرویس‌هاتون استفاده کنید می‌تونید از ابزارهای دیگر نیز استفاده کنید.
نکته:
قبل از اینکه شروع کنیم این نکته رو بگم که ما درفریم ورک NestJS قرار نیست فایل YAML یا JSON سواگر رو بنویسیم چون خود NestJS برای ما این فایل رو می سازه ( Generate میکنه! ). اما اگر میخواهید ساختار این فایل رو ببینید و خودتون پیاده سازی کنید می تونید به Documentation سواگر مراجعه کنید. ساختار به شدت قابل فهم برای انسان هست و به هیچ عنوان پیچیدگی خاصی نداره با یک بررسی ساده متوجه این قضیه خواهید شد.
بعد از نصب NestJS برای ایجاد یک پروژه در دایرکتوری مورد نظرتون یک ترمینال باز کنید و کامند زیر را وارد کنید:
بعد از به اتمام رسیدن مراحل ایجاد فایل‌ها و ساختار کلی پروژه شما توسط NestJS شما می توانید با کامند yarn start:dev پروژه‌تون رو در حالت development اجرا کنید. بله شما یک وب سرویس HTTP ایجاد کردید! :))
قرار نیست راجب NestJS صحبت کنیم فقط به صورت خلاصه یکم بررسی می‌کنیم تا درک بهتری داشته باشیم اگر میخواهید NestJS رو درک کنید بهتره به Documentation این فریم ورک مراجعه کنید. توجه داشته باشید NestJS علاقه‌ای به ما ایرانی ها نداره! خودتون می‌دونید چطوری باید نسبت به این موضوع بی اهمیت باشید?
اگر به ساختار پروژه‌تون نگاه کنید شامل چند بخش اصلی هست:
فایل app.module.ts ساختار اصلی اپلیکیشن و تعریف بخش های مختلف رو انجام میده.
فایل main.ts که پیکربندی وب سرویس و اپلیکیشن شما رو انجام میده.
فایل app.service.ts شما می‌تونید سرویس های اپلیکیشن‌تون رو در کلاس AppService ( یا هر اسم دیگه ای) تعریف کنید.
فایل app.controller.ts شما می‌تونید کنترلر هاتون رو در این کلاس تعریف کنید.
و بخش های دیگر که خیلی مرتبط با این بحث نیست.
برای اینکار ابتدا لازم هست پکیج سواگر رو در دایرکتوری پروژه‌تون نصب کنید (راستی من برای نصب پکیج ها از yarn استفاده میکنم شما می‌تونید از npm یا pnpm استفاده کنید.)
در اصل شما دو پکیج رو نصب می‌کنید یکی nestjs/swagger@ شامل متد های سواگر هست و swagger-ui-express کار بصری سازی ( visualizing ) APIهای شما رو انجام میده.
برای راه‌اندازی سواگر ( Config ) کافیه داخل فایل main.ts یک نمونه ( Instance ) از کلاس DocumentBuilder سواگر ایجاد کنید و تنظمات اصلی سواگر رو در آن راه‌اندازی و کانفیگ کنید:
بعد از پیاده سازی اولیه سواگر کافیه HTTP Server خودتون رو اجر کنید برای اینکار همانطور که گفته شد در دایرکتوری پروژه‌تون کافیه کامند start yarn:dev رو اجرا کنید. حالا کافیه در مرورگر وارد http://localhost:3000/api بشید.
برای دیدن فایل JSON سواگرتون که قبلا توضیحاتشو دادم کافیه وارد http://localhost:3000/api-json بشید.
برای توصیف API هاتون وارد app.controller.ts شوید جایی که API های شما در آن تعریف میشود. هنگام راه اندازی NestJS برای شما یک API به صورت مثال تعریف می‌کند که درخواست ها با متد GET را دریافت می‌کند. برای توصیف این متد (که درخواست ها ( Request )شامل چه مواردی هست و پاسخ ها ( Response ) چه مقادیری هستند) دکوریشن ( Decoration ) های زیادی وجود دارد. ( برای آشنایی با مفهموم درکوریشن ها می توانید به مستندات NestJS مراجعه کنید ) که من در این مطلب چندتا از مهمترین هاشو بررسی میکنم.
دکوریشن ( )ApiProperty@:
برای توصیف پارامترهای ارسالی به متدهاتون DTO ( Data Transfer Object ) می‌توانید از این دکوریشن استفاده کنید.
برای مثال من در این پروژه یک دایرکتوری در src به نام dto ایجاد میکنم و فایل get-hello.dto.ts رو در آن ایجاد می کنم.
البته خیلی آپشن های دیگری نیز در ApiProperty وجود دارد که می‌توانید با توجه به نیازتون آن ها رو تعریف کنید. به این صورت DTO های شما در داکیومنت سواگر توصیف می شود.
دکوریشن ( )ApiTags@ :
اگر نیاز دارید در swagger docs تون API هاتون رو دسته بندی کنید می تونید از این دکوریشن در کنترلرتون استفاده کنید مقدار پیش فرض اگر به عکس ( رابط کاربری سواگر ) که در بالا آورده شده نگاه کنید مقدار default می باشد.
دکوریشن ( )ApiOperation@
برای توصیف و خلاصه‌ای از نتیجه نهایی این متد می توانید از این دکوریشن استفاده کنید. اینکه به صورت خلاصه این API در نهایت چیکار میکنه و توصیف بیشتر از اون. این دکوریشن رو می‌توانید در بالای متدتون تعریف کنید.
دکوریشن ( )ApiResponse@
برای توصیف ساختار پاسخ ( Response ) می‌توانید از این دکوریشن در بالای متدتون استفاده کنید اینکه ریسپانس چه کد وضعیتی داره ( status )، و توصیف اون و مقادیر آن.
دکوریشن های دیگر نیز به همین صورت تعریف میشود. اگر نیاز به توصیف param هاتون دارید از دکوریشن ApiParam اگر میخواهید بادی درخواستتون رو توصیف کنید از ApiBody و اگر میخواهید query هاتون رو توصیف کنید ApiQuery استفاده کنید درست مانند دکوریشن هایی که مثال زدیم.
همانطور که دیدید استفاده از swagger بسیار ساده و کاربردی هست بدیهی هست که نمیشه در این مطلب همه‌ی امکانات سواگر رو بررسی کنیم قطعا نیاز هست در حین انجام پروژه اونها رو پیدا کنید و ازشون استفاده کنید.
و در نهایت swagger docs شما به این صورت خواهد شد:
در کل ممنونم که تا اینجا همراه من بودید همانطور که مشاهده کردید برای طراحی یک Open API استاندارد شما نیاز به این ابزار دارید اگر این مطلب براتون مفید بود با دوستانتون به اشتراک بزارید یا اگر جایی از اون گنگ بود برام کامنت بزارید.
