راهنمای مستندات و ابزار swagger

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

در نسخه جدید وب‌سرویس‌های وان‌سرویس، از معماری و استاندارد REST بهره گرفته‌ایم. همچنین، مستندات سرویس‌ها بر اساس استاندارد OpenAPI 3.0.0 تهیه و تدوین شده است تا شفافیت و کاربردی بودن آن‌ها بهبود یابد.

مستندات سرویس‌ها از طریق ابزار قدرتمند Swagger ارائه و میزبانی می‌شود. این ابزار امکان اجرای مستقیم درخواست‌ها و آزمایش سرویس‌ها را در همان صفحه مستندات فراهم کرده و تجربه‌ای کارآمد و ساده‌تر برای کاربران ایجاد می‌کند.

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

قدم اول: ثبت نام و دریافت رمزینه (توکن)

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

در معماری جدید وبسرویس ها، رمزینه از طریق هدر (Header) درخواست و به شکل زیر تنظیم میشوند، این هدر باید در تمامی درخواست های شما به وان سرویس وجود داشته باشد در غیر اینصورت با کد خطای 401 (رمزینه تنظیم نشده یا اشتباه است) مواجه خواهید شد!

در ابزار Swagger با انجام مراحل زیر میتوانید رمزینه یا توکن اختصاصی خودتان را تنظیم کنید:

کافیست با کلیک بر روی دکمه Authorize و رمزینه را وارد و ثبت کردن کنید.

در ادامه میتوانید با انتخاب API موردنظر اقدام به تست و بررسی نمایید.

قدم دوم: HTTP Methods

با توجه به اینکه تمامی سرویس‌های وان‌سرویس بر پایه پروتکل و ساختار HTTP ارائه و میزبانی می‌شوند، درخواست‌ها می‌توانند با استفاده از یکی از متدهای GET، POST، DELETE یا OPTIONS تنظیم شوند.

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

قدم سوم: تنظیم پارامتر ها

طبق استاندارد REST، بسته به نوع وب‌سرویس و ساختار آن، پارامترها می‌توانند به یکی از سه روش Query String، API Path یا Request Body مقداردهی شوند. در ادامه به توضیح هر یک از این روش‌ها می‌پردازیم:

روش Query String

در این روش، پارامترها در انتهای آدرس API قرار گرفته و به شکل زیر مقداردهی می‌شوند:

• هر پارامتر با علامت = مقداردهی می‌شود.
• پارامترها با علامت & از یکدیگر جدا می‌شوند.

در تصویر زیر، دو پارامتر q و page به صورت Query String مقداردهی شده‌اند. پارامتر اول (q) اجباری است، درحالی‌که پارامتر دوم (page) اختیاری می‌باشد:

روش API Path

در این روش، مقدار پارامتر در بخشی از مسیر API قرار می‌گیرد. به نمونه زیر توجه کنید:

در این مثال، مقدار 100123 نشان‌دهنده پارامتر موردنظر است. در تصویر زیر نمونه مشابهی در ابزار Swagger نشان داده شده است:

در این حالت، پارامتر id از طریق API Path و پارامترهای index و limit از طریق Query String مقداردهی می‌شوند.

روش Request Body

در این روش، پارامترها به‌صورت داده‌های JSON در بدنه درخواست (Request Body) ارسال می‌شوند. این روش معمولاً برای درخواست‌های POST استفاده می‌شود. نمونه:

قدم سوم: ارسال درخواست و دریافت نتیجه

در ابزار Swagger، با کلیک بر روی گزینه Try it out، می‌توانید پارامترهای موردنظر خود را تنظیم کرده و سپس با استفاده از دکمه Execute درخواست خود را ارسال کنید. نتیجه درخواست، شامل پاسخ سرور و جزئیات مرتبط، در ادامه صفحه مستندات نمایش داده خواهد شد.

یکی از قابلیت‌های مفید این ابزار، تولید دستور cURL متناسب با درخواست تنظیم‌شده است. نمونه دستورهای تولیدشده برای مثال‌های قبلی در زیر آورده شده است:

علاوه بر این، شما می‌توانید دستور cURL تولیدشده را با استفاده از ابزارهایی مانند Curlconverter به کد معادل در زبان برنامه‌نویسی دلخواه خود تبدیل کنید. این قابلیت به شما کمک می‌کند که براحتی کد تولید شده معادل درخواستی که ارسال و تست کرده اید را مستقیماً در اپلیکیشن یا پروژه خود وارد و استفاده کنید.

درون ریزی در سایر ابزار ها

به لطف استفاده از استاندارد OpenAPI در نگارش مستندات، شما می‌توانید به‌راحتی با درون‌ریزی لینک فایل مستندات در ابزارهایی نظیر Postman، سرویس‌ها و APIهای موردنظر را تست و اجرا کنید.

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