توليد Swagger/OpenAPI لـ TypeScript: أفضل الأدوات

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

\n\n

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

\n\n

لماذا يجب استخدام التوليد من OpenAPI؟

\n

OpenAPI (المعروف سابقًا باسم Swagger) هو معيار لوصف REST API. باستخدام ملف مواصفات بصيغة YAML أو JSON، تحصل على:

\n

\n
• تحديد أنواع بنسبة 100% — واجهات TypeScript تتطابق تمامًا مع مخطط الطلبات والاستجابات
\n
• مزامنة مع الواجهة الخلفية (Backend) — عند تغيير API، يكفي إعادة توليد الكود
\n
• تقليل الأخطاء — يكتشف مترجم TypeScript عدم تطابق الأنواع في مرحلة التطوير
\n
• الإكمال التلقائي في بيئة التطوير (IDE) — يوفر IntelliSense اقتراحات للحقول والأنواع
\n

\n\n

أفضل أدوات توليد TypeScript من OpenAPI

\n\n

1. openapi-typescript-codegen (موصى به)

\n

حظيت هذه الأداة بشعبية كبيرة بفضل بساطتها ونهجها الحديث. تقوم بتوليد كود نظيف ومنظم جيدًا مع دعم axios أو fetch.

\n\n

التثبيت:

\n

npm install -D openapi-typescript-codegen

\n\n

مثال على الاستخدام:

\n

npx openapi-typescript-codegen --input ./spec.yaml --output ./generated --client axios

\n\n

الكود المولد:

\n

// generated/models/User.ts\nexport interface User {\n    id: number;\n    name: string;\n    email: string;\n    role: 'admin' | 'user';\n}\n\n// generated/services/UserService.ts\nexport class UserService {\n    public async getUsers(): Promise<User[]> {\n        return this.httpRequest.request({\n            method: 'GET',\n            url: '/users',\n        });\n    }\n}

\n\n

المزايا:

\n

\n
• دعم OpenAPI 3.0 و 3.1
\n
• توليد النماذج والخدمات والأنواع للطلبات
\n
• توليد اختياري لـ hooks الخاصة بـ React Query
\n
• قوالب قابلة للتخصيص عبر Handlebars
\n

\n\n

2. OpenAPI Generator (openapi-generator)

\n

المولد الرسمي من مجتمع OpenAPI. يدعم أكثر من 50 لغة، بما في ذلك TypeScript (عدة مولدات).

\n\n

التثبيت:

\n

npm install -D @openapitools/openapi-generator-cli

\n\n

مثال على الاستخدام:

\n

npx openapi-generator-cli generate \\\n    -i spec.yaml \\\n    -g typescript-axios \\\n    -o ./generated

\n\n

الكود المولد:

\n

// generated/api.ts\nexport const UsersApiAxiosParamCreator = {\n    getUsers: async (options?: AxiosRequestConfig): Promise<RequestArgs> => {\n        const localVarPath = `/users`;\n        return {\n            url: localVarPath,\n            method: 'GET',\n        };\n    }\n}

\n\n

الميزات:

\n

\n
• المولدات: typescript-axios، typescript-fetch، typescript-angular
\n
• دعم التفويض (OAuth2، API Key)
\n
• توليد الوثائق والاختبارات
\n
• العمل عبر CLI أو إضافات Maven/Gradle
\n

\n\n

3. swagger-typescript-api

\n

مولد خفيف وسريع، يركز على TypeScript النظيف بدون تبعيات إضافية.

\n\n

التثبيت:

\n

npm install -D swagger-typescript-api

\n\n

مثال على الاستخدام:

\n

npx swagger-typescript-api -p ./spec.yaml -o ./generated -n api.ts

\n\n

الكود المولد: