Orval ابزاری کارآمد است که قادر به تولید کلاینتهایی با امضاهای نوع (Type-Signatures) مناسب در تایپاسکریپت (TypeScript) از هر مشخصات معتبر OpenAPI نسخه ۳ یا Swagger نسخه ۲ است. این مشخصات میتوانند در قالبهای YAML یا JSON ارائه شوند.
انگیزه و هدف اصلی توسعه
توسعهدهندگان غالباً از سوآگر (Swagger) به عنوان یک قرارداد بین تیمهای فرانتاند (Frontend) و بکاند (Backend) استفاده میکنند. قبل از ظهور Orval، ابزارهایی مانند سوآگر ادیتور (Swagger Editor) یا سوآگر کدجن (Swagger Codegen) در دسترس بودند، اما این ابزارها به تنهایی نیازهای توسعهدهندگان را به طور کامل برآورده نمیکردند. همین امر انگیزهای برای ایجاد Orval شد تا کاستیهای موجود را جبران کند و فرآیند توسعه را تسهیل بخشد.
اهداف کلیدی Orval
Orval بر سه هدف اصلی متمرکز است که به بهبود گردش کار توسعهدهندگان کمک شایانی میکند:
- تولید مدلهای تایپاسکریپت (TypeScript Models): این ابزار قادر است مدلهای دادهای مورد نیاز را با دقت و بر اساس ساختار تعریف شده در مشخصات API، به صورت خودکار در قالب تایپاسکریپت تولید کند.
- تولید فراخوانهای HTTP (HTTP Calls): Orval میتواند کدهای لازم برای انجام درخواستهای HTTP به API را تولید کند، که این امر نیاز به نوشتن دستی کدهای تکراری را از بین میبرد.
- تولید ماک (Mocks) با MSW: این ابزار قابلیت تولید ماکهایی را فراهم میکند که با کتابخانه MSW (Mock Service Worker) سازگار هستند. این قابلیت به توسعهدهندگان فرانتاند اجازه میدهد تا بدون نیاز به بکاند واقعی، به تست و توسعه بخش فرانتاند بپردازند.
کلاینتهای تولید شده
کلاینت پیشفرض (Default Client) تولید شده توسط Orval از کتابخانه axios استفاده میکند و میتواند با Workspace API یا فریمورکهای جاوااسکریپت (JavaScript Frameworks) محبوبی نظیر Angular، React یا Vue مورد استفاده قرار گیرد. این کلاینت در واقع یک تابع است که یک نمونه از axios یا یک تابع از Workspace API را به عنوان آرگومان دریافت کرده و یک شی (Object) بازمیگرداند. هر کلید (Key) در این شی، تابعی است که فراخوانی HTTP را تنظیم و اجرا میکند. علاوه بر کلاینت پیشفرض، Orval قابلیت تولید کلاینتهای دیگری را نیز دارد که عبارتند از:
- React Query با
axios: این کلاینت برای فریمورک React و کتابخانه React Query به همراه axios تولید میشود که مدیریت وضعیت (State Management) و دریافت داده (Data Fetching) را در برنامههای React بهبود میبخشد. - Angular با
HttpClient: برای توسعهدهندگان Angular، Orval میتواند کلاینتی را تولید کند که از سرویس HttpClient فریمورک Angular برای انجام درخواستهای HTTP استفاده میکند.