OpenAPI Generator هي أداة مفتوحة المصدر تحول مواصفات OpenAPI أو Swagger إلى تعليمات برمجية عاملة: حزم SDK للعميل، وجذوع الخادم، وملفات التكوين. تقوم بتثبيت واجهة سطر الأوامر (CLI) الخاصة بها، وتوجهها إلى مواصفاتك، وتختار مولدًا مثل typescript-axios أو spring، وهي تكتب التعليمات البرمجية في مجلد إخراج. يوضح لك هذا الدليل كيفية تثبيتها، وسرد المولدات المتاحة، وإنتاج العملاء والخوادم للعديد من اللغات.
ما هو OpenAPI Generator
يقرأ OpenAPI Generator وصفًا لـ API قابل للقراءة آليًا وينتج منه كودًا مصدريًا. زوده بملف openapi.yaml (أو JSON) ويمكنه إنشاء مكتبة عميل لاستدعاء واجهة برمجة التطبيقات هذه، وجذع خادم يقوم بتطبيقها، بالإضافة إلى المستندات والتكوين.
وهو يدعم كلاً من OpenAPI v2 (تنسيق Swagger الأقدم) و OpenAPI v3. يتم صيانة المشروع بواسطة منظمة OpenAPITools على GitHub، مع قوالب لعشرات اللغات والأطر.
التمييز الرئيسي: هذا هو مولد للتعليمات البرمجية، وليس مولدًا للوثائق. أدوات التوثيق مثل Swagger UI أو Redoc تعرض مواصفاتك في صفحات HTML قابلة للقراءة البشرية. بدلاً من ذلك، ينتج OpenAPI Generator تعليمات برمجية تقوم بتجميعها وشحنها. يمكنه أيضًا إصدار مستندات Markdown، ولكن وظيفته الرئيسية هي حزم SDK وجذوع التعليمات البرمجية.
كيف يرتبط بـ Swagger Codegen
إذا كنت قد استخدمت Swagger Codegen، فسيبدو لك OpenAPI Generator مألوفًا. لقد تم فصله عن Swagger Codegen في مايو 2018، بين إصداري Swagger Codegen 2.3.1 و 2.4.0، بواسطة أكثر من 40 من كبار المساهمين ومنشئي القوالب فيه.
حدث الانفصال بعد خلاف حول اتجاه Swagger Codegen 3.0.0. أراد المجتمع دورة إصدار أسرع وأكثر انفتاحًا. تصف ملاحظات الانفصال الرسمية المشروع بأنه يستند إلى Swagger Codegen 2.4.0-SNAPSHOT، لذا يتشاركان جذورًا عميقة. إذا كنت تقارن بين الاثنين، فإن تحليل بدائل Swagger Codegen يغطي الاختلافات العملية.
تثبيت OpenAPI Generator
لديك أربعة مسارات تثبيت شائعة. اختر المسار الذي يناسب حزمة التكنولوجيا الخاصة بك.
npm (الأكثر شيوعًا)
مغلف npm هو أسهل نقطة دخول لمعظم الفرق. يقوم بتنزيل وإدارة ملف JAR الأساسي نيابة عنك.
npm install @openapitools/openapi-generator-cli -g
يمكنك أيضًا تشغيله بدون تثبيت عام:
npx @openapitools/openapi-generator-cli version
Homebrew (لنظام macOS)
brew install openapi-generator
ملف JAR مستقل
OpenAPI Generator هو تطبيق Java، لذا يمكنك تنزيل ملف JAR مباشرةً من Maven Central وتشغيله باستخدام Java. هذا يتجنب طبقة npm أو Homebrew بالكامل.
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar help
تحقق من Maven Central للحصول على أحدث رقم إصدار قبل التنزيل.
Docker
تتيح لك الصورة الرسمية إنشاء كود دون تثبيت أي شيء محليًا. قم بتركيب دليل العمل الخاص بك في الحاوية حتى تتمكن من قراءة مواصفاتك وكتابة الإخراج مرة أخرى.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
سرد المولدات المتاحة
قبل أن تقوم بإنشاء أي شيء، تعرف على المولدات الموجودة. يستهدف كل مولد لغة بالإضافة إلى إطار عمل، مثل java أو python أو spring.
openapi-generator-cli list
لعرض موجز، سطر واحد لكل عنصر، استخدم العلم القصير وقسّم على الفواصل:
openapi-generator-cli list -s | tr ',' '\n'
تقوم القائمة بفصل مولدات العميل (لاستدعاء واجهة برمجة التطبيقات) عن مولدات الخادم (لتطبيقها)، بالإضافة إلى مولدات التوثيق والمخططات.
إنشاء حزمة SDK للعميل
الأمر الأساسي هو generate. يأخذ ثلاثة وسائط ستستخدمها في كل مرة:
-i, --input-specيشير إلى ملف المواصفات أو عنوان URL الخاص بك.-g, --generator-nameيحدد المولد الذي سيتم تشغيله.-o, --outputيحدد دليل الإخراج.
إليك عميل TypeScript مبني على Axios:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
يقوم ذلك بكتابة عميل ذو أنواع إلى ./client. يصبح كل عملية في مواصفاتك طريقة، وكل مخطط يصبح نموذجًا.
يعمل نفس النمط عبر اللغات. قم بتبديل اسم المولد ومجلد الإخراج:
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
بما أن الكود يأتي من مواصفة واحدة، فإن كل عميل يظل متوافقًا مع العقد. عندما تتغير المواصفات، تقوم بإعادة الإنشاء وتتبع حزم SDK الخاصة بك.
إنشاء جذوع الخادم
مولدات الخادم تعكس الاتجاه. بدلاً من الكود الذي يستدعي واجهة برمجة التطبيقات الخاصة بك، تحصل على هيكل يقوم بتطبيقها، مع التوجيه، ونماذج الطلبات، وواجهات المعالجات المجهزة. أنت تملأ منطق العمل.
إليك جذع خادم Spring Boot:
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
يمنحك المشروع المُنشأ وحدات تحكم (controllers) وكائنات نقل البيانات (DTOs) تتطابق مع مواصفاتك. تقوم بتطبيق طرق الواجهة، ويتم تعريف أشكال الطلب والاستجابة لك بالفعل. هذا يحافظ على توافق الخادم قيد التشغيل مع العقد المنشور.
تكوين الإخراج
نادراً ما يكون الإخراج الافتراضي هو بالضبط ما تريده. يمنحك OpenAPI Generator عدة عناصر تحكم.
خصائص إضافية
تعرض معظم المولدات خيارات لكل لغة عبر --additional-properties (اختصار -p). قم بتمريرها كأزواج key=value مفصولة بفاصلة:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
يوثق كل مولد خصائصه الخاصة، لذا تحقق من صفحة المولد للحصول على القائمة الكاملة للمفاتيح التي يقبلها.
ملف تكوين
عندما يطول سطر الأوامر، انقل الخيارات إلى ملف تكوين. يتم دعم كل من JSON و YAML.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
يحافظ ملف التكوين على إعدادات الإنشاء الخاصة بك في التحكم بالإصدار بجوار المواصفات، مما يجعل عمليات البناء قابلة للتكرار.
تجاهل الملفات
يقرأ OpenAPI Generator ملف .openapi-generator-ignore في دليل الإخراج. يستخدم نفس صيغة .gitignore. استخدمه لمنع المولد من الكتابة فوق الملفات التي قمت بتعديلها يدويًا.
# .openapi-generator-ignore
*.md
src/custom/**
يمكنك الإشارة إلى ملف التجاهل في موقع آخر باستخدام --ignore-file-override <location>.
قوالب مخصصة
يتم تشغيل كل مولد بواسطة قوالب Mustache. إذا كان الإخراج الافتراضي لا يتطابق مع نمطك الخاص، فانسخ القوالب، وقم بتحريرها، ومرر دليلك باستخدام -t:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
هذه هي الأداة المناسبة عندما تحتاج إلى رأس مخصص، أو عميل HTTP مختلف، أو اصطلاحات تسمية داخلية مدمجة في كل ملف تم إنشاؤه.
تشغيله في CI (التكامل المستمر)
ينتمي إنشاء التعليمات البرمجية إلى مسار عملك (pipeline)، وليس على جهاز كمبيوتر محمول لمطور واحد. أعد إنشاء العميل عند كل تغيير في المواصفات حتى لا تبتعد حزمة SDK الملتزم بها عن العقد. إليك خطوة GitHub Actions باستخدام npx:
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
يمكنك إفشال عملية البناء إذا اختلف الإخراج المعاد إنشاؤه عما هو ملتزم به، مما يكتشف المواصفات وحزم SDK التي خرجت عن التزامن.
اجعل المواصفة مصدرك الوحيد للحقيقة
لا يكون OpenAPI Generator جيدًا إلا بقدر جودة المواصفات التي تغذيها به. إدخال خاطئ، إخراج خاطئ: مواصفات غامضة أو غير صالحة تنتج حزمة SDK غامضة أو معطلة. لذا، فإن الخطوة الأكثر قيمة تحدث قبل أن تقوم بتشغيل generate على الإطلاق. تتأكد من أن المواصفات صحيحة، كاملة، ومستقرة.
هنا يأتي دور Apidog. Apidog هي منصة API متكاملة تدعم OpenAPI أصلاً، لذا فإن عمل تصميمك ومواصفاتك هما نفس الأثر. تقوم بتصميم أو استيراد واجهة برمجة التطبيقات، ويحتفظ Apidog بمستند OpenAPI كمصدر وحيد للحقيقة الذي يتدفق منه كل شيء آخر.
سير عمل نظيف يبدو كالتالي:
- صمم أو استورد مواصفات OpenAPI في Apidog. يسمح لك دعم الفروع بالعمل على التغييرات بشكل منفصل، على غرار التحكم في إصدار OpenAPI باستخدام Git.
- تحقق من صحة المواصفات ونظفها قبل الإنشاء. تنتج المواصفات التي تجتاز مدقق OpenAPI (linter) و مدقق Swagger (validator) كودًا أنظف مع مفاجآت أقل.
- صدر المواصفات التي تم التحقق منها، ثم زود بها OpenAPI Generator لحزم SDK وجذوع التعليمات البرمجية الخاصة بك.
يمكنك أيضًا إبقاء المواصفات متزامنة مع مستودعك، على سبيل المثال عن طريق مزامنة مواصفات OpenAPI مع GitHub، ومراجعة التغييرات باستخدام مقارنة OpenAPI (diff) قبل شحنها. إذا كنت تنتقل من أدوات أقدم، فإن مقارنة بدائل Swagger لتصميم واختبار API تعد نقطة انطلاق جيدة.
أين يتوقف Apidog ويبدأ OpenAPI Generator
من الجدير بالذكر أن نكون دقيقين هنا. لا يقوم Apidog بإنشاء حزم SDK كاملة للعميل أو جذوع خادم. هذه مهمة OpenAPI Generator، والاثنان متكاملان بدلاً من أن يكونا متنافسين.
يوفر لك Apidog مقتطفات طلبات العميل جاهزة للنسخ لكل نقطة نهاية، بالعديد من اللغات وعملاء HTTP. هذه أمثلة لكل طلب يمكنك لصقها في نص برمجي، وليست حزمة SDK جاهزة. للحصول على مكتبة مُنشأة ومُدارة بالإصدارات أو هيكل خادم، تقوم بتشغيل OpenAPI Generator على المواصفات التي ينتجها Apidog.
يشحن Apidog أيضًا أداة تشغيل الاختبارات الخاصة به لسطر الأوامر، وهي واجهة سطر الأوامر لـ Apidog (Apidog CLI)، وهي منفصلة عن إنشاء التعليمات البرمجية. يقوم بتشغيل اختبارات API الخاصة بك في CI؛ ولا يقوم بإنشاء حزم SDK. قم بتثبيته واستخدامه كالتالي:
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
يمكنك تمرير المصادقة باستخدام --access-token، ويحدد -t سيناريو الاختبار، ويختار -e البيئة التي سيتم الاختبار عليها، ويحدد -r أدوات إعداد التقارير. قم بتشغيله على إصدار Node.js LTS الحالي. للحصول على تفاصيل الإعداد، راجع دليل تثبيت Apidog CLI والدليل التفصيلي حول اختبار REST API من سطر الأوامر.
لذا فإن الدورة الكاملة هي: تصميم والتحقق من المواصفات في Apidog، وإنشاء حزم SDK وجذوع التعليمات البرمجية باستخدام OpenAPI Generator، ثم التحقق من واجهة برمجة التطبيقات قيد التشغيل باستخدام Apidog CLI.
جرب Apidog مجانًا، لا يلزم وجود بطاقة ائتمان.
الأسئلة المتكررة
ما هو OpenAPI Generator؟
OpenAPI Generator هي أداة مفتوحة المصدر من منظمة OpenAPITools تقوم بإنشاء تعليمات برمجية من مواصفات OpenAPI أو Swagger. تنتج حزم SDK للعميل، وجذوع الخادم، والوثائق، وملفات التكوين، وتدعم كلاً من OpenAPI v2 و v3.
كيف تستخدم OpenAPI Generator؟
قم بتثبيت واجهة سطر الأوامر (CLI) (على سبيل المثال npm install @openapitools/openapi-generator-cli -g)، ثم قم بتشغيل generate بثلاثة علامات: -i لمواصفاتك، و-g للمولد، و-o لمجلد الإخراج. قم بتشغيل openapi-generator-cli list أولاً للاطلاع على جميع المولدات المتاحة.
كيف يعمل OpenAPI Generator؟
يقوم بتحليل مواصفاتك إلى نموذج داخلي، ثم يعرض هذا النموذج عبر قوالب Mustache للهدف الذي اخترته. تصبح كل عملية طريقة أو معالجًا، ويصبح كل مخطط نموذجًا مُحدد النوع. يمكنك تجاوز القوالب باستخدام -t لتغيير الإخراج.
كيف تنشئ حزمة SDK للعميل من مواصفات OpenAPI؟
اختر مولد عميل وقم بتشغيل generate. على سبيل المثال، يقوم الأمر openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client بإنشاء عميل TypeScript مُحدد النوع. استبدل typescript-axios بـ java أو python أو go لاستهداف لغات أخرى.
كيف تنشئ جذوع الخادم؟
اختر مولد خادم. لهيكل Spring Boot، قم بتشغيل openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring. يتضمن الإخراج وحدات التحكم ونماذج الطلبات من مواصفاتك، وتقوم أنت بتطبيق منطق المعالج.
ما الفرق بين OpenAPI Generator و Swagger Codegen؟
تم فصل OpenAPI Generator عن Swagger Codegen في مايو 2018 بواسطة أكثر من 40 من مساهميه، الذين أرادوا دورة إصدار أسرع ومدفوعة بالمجتمع. يتشاركان أساسًا مشتركًا، لكن OpenAPI Generator لديه الآن خارطة طريقه الخاصة به، ومجموعة المولدات، وجدول الإصدارات.
كيف تنشئ حزمة PHP SDK من مواصفات OpenAPI؟
استخدم مولد php: openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php. قم بتشغيل openapi-generator-cli list لتأكيد اسم المولد الدقيق ولرؤية خيارات إطار عمل PHP الأخرى قبل الإنشاء.