DEV Community

Cover image for OpenAPI Generator: كيفية إنشاء عميل API وكود الخادم
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

OpenAPI Generator: كيفية إنشاء عميل API وكود الخادم

OpenAPI Generator هي أداة مفتوحة المصدر تحول مواصفات OpenAPI أو Swagger إلى كود قابل للاستخدام: حزم SDK للعميل، جذوع خادم، ملفات إعداد، وتوثيق. عمليًا، تثبّت واجهة سطر الأوامر، تمرر لها ملف openapi.yaml أو رابط المواصفة، تختار مولدًا مثل typescript-axios أو spring، ثم تحصل على مشروع جاهز داخل مجلد إخراج.

جرّب Apidog اليوم

ما هو OpenAPI Generator

يقرأ OpenAPI Generator وصفًا آليًا لـ API وينشئ منه كودًا مصدريًا. إذا كان لديك ملف openapi.yaml أو JSON، يمكنك استخدامه لإنشاء:

  • مكتبة عميل لاستدعاء API.
  • جذع خادم لتطبيق نفس العقد.
  • نماذج بيانات وملفات إعداد.
  • توثيق أو ملفات مساعدة حسب المولد.

يدعم OpenAPI Generator كلاً من OpenAPI v2، المعروف سابقًا باسم Swagger، و OpenAPI v3. تتم صيانة المشروع بواسطة منظمة OpenAPITools على GitHub، ويحتوي على قوالب لعشرات اللغات والأطر.

النقطة المهمة: OpenAPI Generator ليس أداة توثيق مثل 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

هذه الطريقة مناسبة لمعظم فرق JavaScript و TypeScript. حزمة npm تدير ملف JAR الأساسي نيابة عنك.

npm install @openapitools/openapi-generator-cli -g
Enter fullscreen mode Exit fullscreen mode

للتحقق من التثبيت:

openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

أو شغّله بدون تثبيت عام:

npx @openapitools/openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

Homebrew على macOS 

brew install openapi-generator
Enter fullscreen mode Exit fullscreen mode

ملف JAR مستقل

OpenAPI Generator تطبيق Java، لذلك يمكنك تنزيل ملف JAR وتشغيله مباشرة:

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
Enter fullscreen mode Exit fullscreen mode

تحقق من Maven Central لاستخدام أحدث رقم إصدار قبل التنزيل.

Docker

إذا كنت لا تريد تثبيت أي شيء محليًا، استخدم صورة 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
Enter fullscreen mode Exit fullscreen mode

سرد المولدات المتاحة

قبل إنشاء أي كود، اعرف أسماء المولدات المتاحة. كل مولد يستهدف لغة أو إطار عمل، مثل java أو python أو spring.

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

لعرض قائمة مختصرة، عنصر واحد في كل سطر:

openapi-generator-cli list -s | tr ',' '\n'
Enter fullscreen mode Exit fullscreen mode

سترى مولدات منفصلة للعميل، الخادم، التوثيق، والمخططات. استخدم اسم المولد كما يظهر في القائمة عند تشغيل أمر generate.

إنشاء حزمة 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
Enter fullscreen mode Exit fullscreen mode

سينشئ الأمر عميلًا محدد الأنواع داخل ./client. تتحول كل عملية في المواصفة إلى method، ويتحول كل schema إلى model.

نفس النمط يعمل مع لغات أخرى:

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
Enter fullscreen mode Exit fullscreen mode

عند تحديث المواصفة، أعد تشغيل الأمر لتحديث حزم SDK والحفاظ على توافقها مع عقد API.

إنشاء جذوع الخادم

مولدات الخادم تعمل بالعكس: بدل إنشاء كود يستدعي API، تنشئ هيكلًا لتطبيق API. تحصل عادةً على:

  • routing جاهز.
  • نماذج request و response.
  • interfaces أو controllers.
  • أماكن واضحة لإضافة منطق العمل.

مثال لإنشاء جذع خادم Spring Boot:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-spring
Enter fullscreen mode Exit fullscreen mode

الإخراج يتضمن controllers و DTOs متطابقة مع مواصفاتك. أنت تطبق منطق المعالجات، بينما تبقى أشكال الطلب والاستجابة مرتبطة بالعقد المنشور.

تكوين الإخراج

الإعدادات الافتراضية ليست دائمًا مناسبة لمشروعك. استخدم خيارات التكوين التالية للتحكم في الناتج.

خصائص إضافية

معظم المولدات تدعم خيارات خاصة باللغة عبر --additional-properties أو الاختصار -p.

مثال مع typescript-axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Enter fullscreen mode Exit fullscreen mode

استخدم صفحة المولد لمعرفة الخصائص المدعومة، لأن المفاتيح تختلف حسب اللغة والإطار.

ملف تكوين

عندما يصبح أمر CLI طويلًا، انقل الخيارات إلى ملف JSON أو YAML:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -c config.yaml
Enter fullscreen mode Exit fullscreen mode

مثال بسيط لملف config.yaml:

npmName: "@acme/api-client"
supportsES6: true
withSeparateModelsAndApi: true
Enter fullscreen mode Exit fullscreen mode

وضع ملف التكوين بجانب المواصفة داخل التحكم بالإصدار يجعل عملية التوليد قابلة للتكرار.

تجاهل الملفات

يقرأ OpenAPI Generator ملف .openapi-generator-ignore من مجلد الإخراج. الصيغة مشابهة لـ .gitignore. استخدمه لمنع الكتابة فوق ملفات عدلتها يدويًا.

# .openapi-generator-ignore
*.md
src/custom/**
Enter fullscreen mode Exit fullscreen mode

يمكنك أيضًا تمرير ملف تجاهل من مكان آخر:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --ignore-file-override ./generator-ignore
Enter fullscreen mode Exit fullscreen mode

قوالب مخصصة

كل مولد يعتمد على قوالب Mustache. إذا أردت تغيير بنية الملفات، التسمية، أو نمط الكود، انسخ القوالب وعدلها ثم مررها عبر -t:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -t ./my-templates
Enter fullscreen mode Exit fullscreen mode

استخدم القوالب المخصصة عندما تحتاج إلى رأس موحد للملفات، عميل HTTP مختلف، أو اصطلاحات داخلية يجب تطبيقها على كل ملف مُنشأ.

تشغيل OpenAPI Generator في 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
Enter fullscreen mode Exit fullscreen mode

يمكنك أيضًا جعل البناء يفشل إذا تغيّر الإخراج بعد إعادة التوليد، مما يكشف أن الكود الملتزم به لا يطابق آخر نسخة من المواصفة.

مثال خطوة تحقق بسيطة:

- name: Check generated client is up to date
  run: |
    npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
    git diff --exit-code ./client
Enter fullscreen mode Exit fullscreen mode

اجعل المواصفة مصدر الحقيقة الوحيد

جودة الكود المُنشأ تعتمد مباشرة على جودة مواصفة OpenAPI. إذا كانت المواصفة ناقصة، غامضة، أو غير صالحة، فسيكون الإخراج كذلك. لذلك أهم خطوة تأتي قبل تشغيل generate: تأكد أن المواصفة صحيحة، كاملة، ومستقرة.

هنا يأتي دور Apidog. Apidog منصة API متكاملة تدعم OpenAPI أصلاً، بحيث يصبح تصميم API والمواصفة جزءًا من نفس سير العمل. يمكنك تصميم API أو استيرادها، ثم استخدام مستند OpenAPI كمصدر واحد للحقيقة.

سير عمل عملي:

  1. صمم أو استورد مواصفة OpenAPI في Apidog. دعم الفروع يسمح بالعمل على التغييرات بشكل منفصل، بطريقة مشابهة لـ التحكم في إصدار OpenAPI باستخدام Git.
  2. تحقق من صحة المواصفة قبل التوليد. المواصفات التي تمر عبر مدقق OpenAPI و مدقق Swagger تنتج كودًا أنظف ومفاجآت أقل.
  3. صدّر المواصفة المتحقق منها.
  4. مررها إلى OpenAPI Generator لإنشاء حزم SDK أو جذوع الخادم.
  5. اختبر API الفعلية بعد النشر.

يمكنك أيضًا إبقاء المواصفة متزامنة مع المستودع عبر مزامنة مواصفات OpenAPI مع GitHub، ومراجعة التغييرات باستخدام مقارنة OpenAPI قبل شحنها. إذا كنت تنتقل من أدوات أقدم، فابدأ من مقارنة بدائل Swagger لتصميم واختبار API.

أين يتوقف Apidog ويبدأ OpenAPI Generator

الدوران مختلفان ومتكاملان:

  • Apidog يساعدك على تصميم API، إدارة المواصفة، التحقق منها، وتوثيقها.
  • OpenAPI Generator ينشئ حزم SDK وجذوع خادم من المواصفة.
  • Apidog CLI يشغل اختبارات API في CI.

Apidog لا ينشئ حزم SDK كاملة للعميل أو جذوع خادم. هذه مهمة OpenAPI Generator. لكنه يوفر مقتطفات طلبات جاهزة للنسخ لكل endpoint بعدة لغات وعملاء HTTP. هذه أمثلة طلبات، وليست SDK مُدارة بالإصدارات.

لتشغيل اختبارات API من سطر الأوامر، استخدم Apidog CLI:

npm install -g apidog-cli@latest

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <testScenarioId> \
  -e <envId> \
  -r cli,html \
  -n 1
Enter fullscreen mode Exit fullscreen mode

شرح الخيارات الأساسية:

  • --access-token: تمرير رمز المصادقة.
  • -t: تحديد سيناريو الاختبار.
  • -e: تحديد البيئة.
  • -r: تحديد تقارير الإخراج.
  • -n: عدد مرات التشغيل.

شغّله على إصدار Node.js LTS الحالي. للتفاصيل، راجع دليل تثبيت Apidog CLI والدليل العملي حول اختبار REST API من سطر الأوامر.

الدورة الكاملة تصبح كالتالي: صمم وتحقق من المواصفة في Apidog، أنشئ حزم SDK وجذوع الخادم باستخدام OpenAPI Generator، ثم تحقق من API قيد التشغيل باستخدام Apidog CLI.

جرب Apidog مجانًا، لا يلزم وجود بطاقة ائتمان.

الأسئلة المتكررة

ما هو OpenAPI Generator؟

OpenAPI Generator أداة مفتوحة المصدر من منظمة OpenAPITools تنشئ كودًا من مواصفات OpenAPI أو Swagger. يمكنها إنتاج حزم SDK للعميل، جذوع خادم، وثائق، وملفات إعداد، وتدعم OpenAPI v2 و v3.

كيف تستخدم OpenAPI Generator؟

ثبّت CLI، ثم شغّل generate مع ثلاثة خيارات أساسية: -i للمواصفة، -g للمولد، و -o لمجلد الإخراج.

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

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

استخدم openapi-generator-cli list أولًا لمعرفة أسماء المولدات المتاحة.

كيف يعمل OpenAPI Generator؟

يحلل المواصفة إلى نموذج داخلي، ثم يمرر هذا النموذج إلى قوالب Mustache خاصة بالمولد الذي اخترته. تتحول العمليات إلى methods أو handlers، وتتحول المخططات إلى models محددة النوع. يمكنك تجاوز القوالب باستخدام -t.

كيف تنشئ حزمة SDK للعميل من مواصفات OpenAPI؟

اختر مولد عميل وشغّل generate. مثال:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

لاستهداف لغات أخرى، استبدل typescript-axios بـ java أو python أو go أو غيرها من المولدات المتاحة.

كيف تنشئ جذوع الخادم؟

اختر مولد خادم. لإنشاء هيكل Spring Boot:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-spring
Enter fullscreen mode Exit fullscreen mode

الإخراج يتضمن controllers ونماذج الطلبات والاستجابات، وتقوم أنت بإضافة منطق المعالجات.

ما الفرق بين 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
Enter fullscreen mode Exit fullscreen mode

شغّل openapi-generator-cli list للتأكد من اسم المولد ورؤية أي خيارات أخرى مرتبطة بـ PHP قبل التوليد.

Top comments (0)