توليد Swagger/OpenAPI لـ TypeScript: المكتبات والأدوات

توليد Swagger/OpenAPI لـ TypeScript: أتمتة إنشاء عملاء API

عند تطوير تطبيقات الويب الحديثة باستخدام TypeScript، غالبًا ما تنشأ الحاجة إلى التكامل مع REST API الموصوف عبر مواصفات OpenAPI (المعروفة سابقًا باسم Swagger). الكتابة اليدوية للأنواع والواجهات وكود العميل لا تستهلك الكثير من الوقت فحسب، بل إنها محفوفة بالأخطاء أيضًا، خاصة عند تغيير الواجهة الخلفية. تأتي أدوات التوليد التلقائي لكود TypeScript من مواصفات OpenAPI للمساعدة. في هذه المقالة، سنستعرض ثلاثة حلول شائعة: openapi-typescript و orval و swagger-typescript-api، بالإضافة إلى مقارنة إمكانياتها.

لماذا نحتاج إلى توليد TypeScript من OpenAPI؟

الهدف الرئيسي هو مزامنة الأنواع وكود العميل بين الواجهة الأمامية والخلفية. مزايا التوليد التلقائي:

• أمان الأنواع: تحصل جميع نقاط النهاية ومعاملات الطلبات والاستجابات على أنواع TypeScript صارمة.
• الحداثة: عند تغيير المواصفات، يكفي إعادة توليد الكود دون إجراء تعديلات يدوية.
• تسريع التطوير: يحصل المطور على دوال جاهزة لاستدعاء API مع الإكمال التلقائي (IntelliSense).
• تقليل الأخطاء: يتم استبعاد الأخطاء المطبعية في أسماء الحقول وعدم تطابق الأنواع.

openapi-typescript

مكتبة openapi-typescript (من منشئي openapi-fetch) هي مولد أنواع خفيف الوزن. تقوم بإنشاء واجهات وأنواع TypeScript فقط، دون توليد كود عميل لاستدعاءات API. هذا هو الخيار المثالي للمشاريع التي تحتاج إلى كتابة بيانات بدقة، ولكن طريقة استدعاء API تترك لتقدير المطور (على سبيل المثال، عبر fetch أو axios).

التثبيت:

npm install -D openapi-typescript

مثال على الاستخدام (توليد الأنواع من ملف spec.yaml):

npx openapi-typescript ./spec.yaml -o ./types/api.ts

النتيجة هي ملف يحتوي على أنواع يمكن استيرادها:

import type { paths } from './types/api';

// نوع الاستجابة من GET /userstype UsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

الإيجابيات: البساطة، التوليد السريع، دعم ممتاز للمخططات المعقدة (allOf, oneOf).
السلبيات: لا توجد دوال جاهزة لاستدعاء API، يتطلب غلافًا إضافيًا.

orval

Orval هو مولد قوي لا ينشئ الأنواع فحسب، بل ينشئ أيضًا هوكات React عاملة بالكامل، بالإضافة إلى عملاء لـ axios أو fetch أو Angular. إنه مفيد بشكل خاص في مشاريع React التي تستخدم React Query (TanStack Query).

التثبيت:

npm install -D orval

التكوين في ملف orval.config.ts:

export default {  petstore: {    input: './swagger.yaml',    output: {      target: './src/generated',      client: 'react-query', // أو 'axios', 'fetch', 'angular'    },  },};

تشغيل التوليد:

npx orval

مثال على هوك مولّد:

import { useGetUsers } from './src/generated/users';

function UsersList() {  const { data, isLoading, error } = useGetUsers();  // سيتم كتابة data تلقائيًا}

الإيجابيات: تكامل جاهز مع React Query، دعم الطفرات، إدارة تلقائية للتخزين المؤقت.
السلبيات: حجم كبير من الكود المولد، الارتباط بعميل HTTP محدد.

swagger-typescript-api

تقدم مكتبة swagger-typescript-api توليدًا مرنًا: يمكن الحصول على أنواع بسيطة أو عميل API كامل مع دعم عملاء HTTP مختلفين (axios, fetch). السمة المميزة هي إمكانية تخصيص قوالب التوليد.

التثبيت: