ساخت یک فایل تعریف اپن ای‌پی‌آی (Build an OpenAPI Definition File)
فایل‌های تعریف OpenAPI برای یک API مؤثر حیاتی هستند. یک فایل تعریف OpenAPI مانند یک نقشه، مشخصات فنی و نقشه‌راه در یک مجموعه است. توضیحات OpenAPI به ماشین‌ها می‌گویند که هنگام مواجهه با یک API چه انتظاری باید داشته باشند. در سناریوهای API-اول (API-first)، فایل‌های تعریف OpenAPI حتی می‌توانند خود APIها را تولید کنند. در این حالت، صحت فایل تعریف OpenAPI اهمیت بیشتری پیدا می‌کند.
تولیدکننده‌های فراوانی برای فایل‌های تعریف OpenAPI وجود دارند. با این حال، مشکل با مولدهای خودکار کد این است که ممکن است کاربران ندانند دقیقاً چه کاری انجام می‌دهند. حتی اگر تجربه‌ی نوشتن دستی فایل‌های توضیحات OpenAPI را داشته باشید، ممکن است جزئیات مشخصات را فراموش کنید. همیشه ایده‌ی خوبی است که مهارت‌های OpenAPI خود را تازه کنید تا با آخرین قابلیت‌ها و بهترین شیوه‌ها برای پیاده‌سازی در توضیحات خود آشنا شوید.
برای این منظور، این راهنما را آماده کرده‌ایم تا بیاموزید چگونه از صفر با استفاده از یک ویرایشگر متن، فایل تعریف OpenAPI بسازید. با پایان این راهنما، درک کاملی از هر فیلد و نحوه‌ی ساخت یک تعریف API از ابتدا تا انتها خواهید داشت.
مرحله ۱: اطلاعات و سرورها
اکنون گام‌به‌گام نحوه‌ی ایجاد فایل تعریف OpenAPI را بررسی می‌کنیم. در اینجا، یک تعریف نمونه برای API فهرست کارها (to-do list) می‌سازیم.
ابتدا، در ویرایشگر متن مورد علاقه‌تان، فایلی به نام openapi.yaml در پوشه‌ی اصلی بسازید. اگر فرمت JSON را ترجیح می‌دهید، می‌توانید از آن هم استفاده کنید، اما در اینجا از YAML استفاده می‌کنیم.
در فایل خالی YAML، با اعلام نسخه‌ی OpenAPI که استفاده می‌کنید شروع کنید. ما از نسخه‌ی ۳.۱.۱ استفاده می‌کنیم. سپس برای API خود عنوان، توضیحات و نسخه تعیین کنید.
همان‌طور که در بالا مشاهده می‌کنید، فایل توضیحات OpenAPI با تعیین نسخه‌ی مورد استفاده شروع می‌شود. در اینجا از OpenAPI 3.1.1 استفاده کرده‌ایم.
در مرحله‌ی بعد، نام API در فیلد title تعریف می‌شود. در این مثال، نام API ما «ToDo API» است.
فیلد description توضیح می‌دهد که این API در سطح بالا چه کاری انجام می‌دهد تا هم برای انسان‌ها و هم ماشین‌ها قابل خواندن باشد. این API یک فهرست کار ساده را مدیریت می‌کند.
فیلد version نسخه را مشخص می‌کند — در اینجا ۱.۰.۰. این موضوع زمانی مفید است که بخواهید نسخه‌های مختلف را مدیریت یا منقضی کنید.
سپس باید آدرس پایه‌ی سرور را تعریف کنید:
در نهایت، فیلد servers به توسعه‌دهندگان اجازه می‌دهد آدرسی را که API از آن سرویس‌دهی می‌کند، مشخص کنند.
مرحله ۲: تنظیم مسیرها (Paths)
بخش paths در توضیحات OpenAPI هر نقطه‌ی پایانی (endpoint) از API و نحوه‌ی تعامل با آن را توصیف می‌کند.
فایل YAML ما یک API پایه‌ای CRUD را تعریف می‌کند، بنابراین هر endpoint می‌تواند چندین درخواست HTTP را بپذیرد. مسیر /todos هم درخواست‌های GET و هم POST را پشتیبانی می‌کند.
ابتدا به تعریف GET نگاه می‌کنیم تا بفهمیم هر بخش چگونه قالب‌بندی می‌شود.
حال هر فیلد را توضیح می‌دهیم:
summary مانند description است و عملکرد دستور را شرح می‌دهد.
operationId نامی منحصربه‌فرد به عملیات می‌دهد — در اینجا listTodos.
بخش responses هر کد پاسخ HTTP را تعریف می‌کند. در اینجا فقط ۲۰۰ داریم، اما می‌توان هر تعداد کد وضعیت مورد نیاز را افزود.
بخش content نوع محتوایی که انتظار می‌رود را مشخص می‌کند. در اینجا، پاسخ شامل فایل JSON با آرایه‌ای از داده‌هاست.
بخش items نشان می‌دهد که داده‌های بازگشتی بر اساس schema موجود در #/components/schemas/Todo قالب‌بندی می‌شوند.
اکنون درخواست POST را بررسی می‌کنیم. شبیه GET است، اما کمی متفاوت، چون endpoint باید داده‌ای را دریافت کرده و منبعی را بازگرداند.
این تعریف مشخص می‌کند که درخواست POST به /todos باید شامل یک بدنه درخواست (requestBody) باشد. در صورت ارسال، پاسخ نیز با همان schema قالب‌بندی خواهد شد.
مرحله ۳: انواع رسانه و داده
JSON تنها فرمت پشتیبانی‌شده توسط OpenAPI 3.1.1 نیست. API شما می‌تواند از فرمت‌های زیر نیز استفاده کند:
گزینه text/plain; charset=utf-8 نشان می‌دهد که داده‌ها بدون قالب خاصی ارسال می‌شوند.application/json رایج‌ترین نوع است و برای داده‌های JSON مورد استفاده برنامه‌هاست.
گزینه‌های دیگر انواع سفارشی رسانه را تعریف می‌کنند که کنترل دقیق‌تری بر نوع خروجی می‌دهند.
Schemas به شما اجازه می‌دهند داده‌های بازگشتی را ساختاردهی کنید تا خروجی سازگار و قابل‌پیش‌بینی باشد.
مرحله ۴: افزودن احراز هویت (Authentication)
بیشتر APIها نوعی احراز هویت دارند. می‌توانید نوع احراز هویت مورد پشتیبانی را در بخش security مشخص کنید.
این کد مشخص می‌کند که سیستم باید یک توکن مجازسازی، معمولاً JWT، از کاربر انتظار داشته باشد.
برای افزودن احراز هویت به یک endpoint خاص، مثلاً متد POST، می‌توانید این را اضافه کنید:
انواع معمول احراز هویت شامل:
-
HTTP (Basic, Bearer, Digest)
-
API Key (در Header یا Query یا Cookie)
-
OAuth2
-
OpenID Connect
مرحله ۵: تعریف شِماها (Schemas)
اکنون باید اجزای schema را بسازید تا درخواست‌ها و پاسخ‌ها را قالب‌بندی کنند.
مرحله ۶: مشاهده نتیجه کامل
اکنون که تمام بخش‌ها را نوشتید، فایل را با نام openapi.yaml ذخیره کنید. در اینجا نمونه کامل تعریف API فهرست کارها آورده شده است:
(کد YAML کامل در متن اصلی حفظ می‌شود.)
توجه داشته باشید که فایل‌های تعریف OpenAPI می‌توانند به‌صورت YAML یا JSON نوشته شوند. در این مثال، YAML استفاده شده زیرا خواناتر است.
(کد JSON کامل نیز در متن حفظ شده است.)
مرحله ۷: آزمایش فایل OpenAPI
مرحله بعدی، آزمایش است تا مطمئن شوید فایل با مشخصات OpenAPI سازگار است.
برای آزمایش، می‌توانید فایل openapi.yaml را با یک سرور آزمایشی مستقر کنید. برای این کار، ابتدا ابزار Prism از Stoplight را نصب کنید:
سپس یک سرور آزمایشی اجرا کنید:
اکنون endpoint را با دستور زیر آزمایش کنید:
اگر همه‌چیز درست باشد، خروجی زیر برمی‌گردد:
نتیجه‌گیری نهایی درباره ساخت فایل تعریف OpenAPI
در این آموزش، فایل OpenAPI را از ابتدا نوشتیم تا به‌طور کامل نحوه عملکرد آن را درک کنیم. البته ابزارهایی مانند Swagger OpenAPI Editor قالب‌های آماده ارائه می‌دهند و خطاها را نیز مشخص می‌کنند.
با این حال، این واقعیت که می‌توانید API باکیفیت را تنها با نرم‌افزارهای رایگان و به‌صورت دستی بنویسید، نشان می‌دهد نیازی به ابزارهای گران‌قیمت نیست.
نوشتن دستی فایل‌های OpenAPI به شما درک عمیقی از ساختار درونی API و نحوه تعامل اجزا می‌دهد و فرآیند را شفاف‌تر و آسان‌تر می‌سازد.
