رمز التباهي
Swagger
هذا هو مشروع Swagger Codegen، الذي يسمح بإنشاء مكتبات عميل API (إنشاء SDK)، وقاعدة الخادم والوثائق تلقائيًا وفقًا لمواصفات OpenAPI.
إذا كنت ترغب في المساهمة، يرجى الرجوع إلى الإرشادات وقائمة المهام المفتوحة.
لمزيد من المعلومات، يرجى الرجوع إلى صفحة ويكي والأسئلة الشائعة؟
⚠️ يشير هذا المستند إلى الإصدار 2.X، تحقق هنا من الإصدار 3.X.
كلا الإصدارين 2.X و 3.X من Swagger Codegen متاحان ويتم صيانتهما بشكل مستقل.
ملحوظات:
الإصدارات 2.X ( io.swagger ) و 3.X ( io.swagger.codegen.v3 ) لها معرفات مجموعات مختلفة .
يتم دعم OpenAPI 3.0.X من الإصدار 3.X فقط.
للحصول على معلومات الإصدار الكاملة، الرجاء الرجوع إلى وثائق الإصدار.
حاليًا، يتم دعم اللغات/الأطر التالية:
عملاء API : ActionScript ، وAda ، وApex ، و Bash ، و C# (.net 2.0، 3.5 أو أحدث)، C++ (cpprest، Qt5، Tizen)، Clojure ، Dart ، Elixir ، Elm ، Eiffel ، Erlang ، Go ، Groovy ، Haskell (http -client، Servant)، Java (Jersey1.x، Jersey2.x، OkHttp، Retrofit1.x، Retrofit2.x، Feign، RestTemplate، RESTEasy، Vertx، مكتبة عملاء Google API لـ Java، كن مطمئنًا)، Kotlin ، Lua ، Node.js (ES5 وES6 وAngularJS مع التعليقات التوضيحية لمترجم إغلاق Google) Objective-C و Perl و PHP و PowerShell و Python و R و Ruby و Rust (rust وrust-server) و Scala (akka وhttp4s وswagger-async- httpclient)، Swift (2.x، 3.x، 4.x، 5.x)، Typescript (Angular1.x، Angular2.x، Fetch، jQuery، Node)
بذرة الخادم : Ada ، C# (ASP.NET Core، NancyFx)، C++ (Pistache، Restbed)، Erlang ، Go ، Haskell (Servant)، Java (MSF4J، Spring، Undertow، JAX-RS: CDI، CXF، Inflector، RestEasy ، Play Framework، PKMST)، Kotlin ، PHP (Lumen، Slim، Silex، Symfony، Zend Expressive)، Python (Flask)، NodeJS ، Ruby (Sinatra، Rails5)، Rust (rust-server)، Scala (Finch، Lagom، سكالاترا)
مولدات وثائق API : HTML ، Confluence Wiki
ملفات التكوين : Apache2
الآخرين : جي ميتر
راجع OpenAPI-Spec للحصول على معلومات إضافية حول مشروع OpenAPI.
الإصدار
التوافق
ابدء
مولدات
لإنشاء مكتبة عميل عينة
إنشاء مكتبات من الخادم الخاص بك
التحقق من صحة مواصفات OpenAPI الخاصة بك
إنشاء وثائق HTML API الديناميكية
إنشاء وثائق HTML API الثابتة
تكامل سير العمل
مولدات الانترنت
مساهمة
فريق Swagger Codegen الأساسي
خضعت مواصفات OpenAPI لثلاثة مراجعات منذ الإنشاء الأولي في عام 2010. تتمتع الإصدارات المستقرة الحالية من مشروع Swagger Codegen بالتوافق التالي مع مواصفات OpenAPI:
| نسخة سواجر كودجن | تاريخ الافراج عنه | التوافق مع مواصفات Swagger / OpenAPI | ملحوظات |
|---|---|---|---|
| 3.0.62 ( المستقر الحالي ) | 2024-08-27 | 1.0، 1.1، 1.2، 2.0، 3.0 | العلامة v3.0.62 |
| 2.4.43 ( المستقر الحالي ) | 2024-08-09 | 1.0، 1.1، 1.2، 2.0 | العلامة v2.4.42 |
وإليك أيضًا نظرة عامة على ما سيحدث قريبًا:
| نسخة سواجر كودجن | تاريخ الافراج عنه | التوافق مع مواصفات Swagger / OpenAPI | ملحوظات |
|---|---|---|---|
| 3.0.63-SNAPSHOT (الإصدار الحالي 3.0.0، الإصدار الثانوي القادم) SNAPSHOT | سيتم تحديده لاحقًا | 1.0، 1.1، 1.2، 2.0، 3.0 | إطلاق طفيف |
| 2.4.44-SNAPSHOT (الإصدار الرئيسي الحالي، الإصدار الثانوي القادم) SNAPSHOT | سيتم تحديده لاحقًا | 1.0، 1.1، 1.2، 2.0 | إطلاق طفيف |
للحصول على تفاصيل تفصيلية لجميع الإصدارات، يرجى الاطلاع على قائمة التوافق الكاملة.
لبدء استخدام Swagger Codegen وتشغيله، راجع الأدلة والتعليمات التالية:
المتطلبات الأساسية
مبنى
باستخدام عامل الميناء
بمجرد الانتهاء من إعداد البيئة الخاصة بك، تصبح جاهزًا لبدء إنشاء العملاء و/أو الخوادم.
كمثال سريع، لإنشاء عميل PHP لـ https://petstore.swagger.io/v2/swagger.json، يمكنك تشغيل ما يلي:
استنساخ بوابة https://github.com/swagger-api/swagger-codegencd swagger-codegen
حزمة mvn النظيفة
إنشاء وحدات Java -jar/swagger-codegen-cli/target/swagger-codegen-cli.jar
-i https://petstore.swagger.io/v2/swagger.json
-ل فب
-o /var/tmp/php_api_clientملاحظة: إذا كنت تستخدم نظام التشغيل Windows، فاستبدل الأمر الأخير بـ
وحدات Java -jarswagger-codegen-clitargetswagger-codegen-cli.jar توليد -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
يمكنك أيضًا تنزيل JAR (أحدث إصدار) مباشرةً من maven.org
للحصول على قائمة بالخيارات العامة المتاحة، يمكنك تشغيل ما يلي:
وحدات Java -jar/swagger-codegen-cli/target/swagger-codegen-cli.jar تساعد في الإنشاء
للحصول على قائمة بخيارات PHP المحددة (والتي يمكن تمريرها إلى المولد باستخدام ملف التكوين عبر الخيار -c )، يرجى تشغيل
وحدات جافا -jar/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
يمكنك إنشاء عميل مقابل واجهة برمجة تطبيقات petstore النموذجية على النحو التالي:
./bin/java-petstore.sh
(على نظام التشغيل Windows، قم بتشغيل .binwindowsjava-petstore.bat بدلاً من ذلك)
سيؤدي هذا إلى تشغيل المولد باستخدام هذا الأمر:
إنشاء وحدات Java -jar/swagger-codegen-cli/target/swagger-codegen-cli.jar -i https://petstore.swagger.io/v2/swagger.json - ل جافا -o عينات/العميل/متجر الحيوانات الأليفة/Java
مع عدد من الخيارات. يمكنك الحصول على الخيارات باستخدام أمر help generate (يظهر أدناه النتائج الجزئية فقط):
NAME
swagger-codegen-cli generate - Generate code with chosen lang
SYNOPSIS
swagger-codegen-cli generate
[(-a | --auth )]
[--additional-properties ...]
[--api-package ] [--artifact-id ]
[--artifact-version ]
[(-c | --config )]
[-D ...] [--git-repo-id ]
[--git-user-id ] [--group-id ]
[--http-user-agent ]
(-i | --input-spec )
[--ignore-file-override ]
[--import-mappings ...]
[--instantiation-types ...]
[--invoker-package ]
(-l | --lang )
[--language-specific-primitives ...]
[--library ] [--model-name-prefix ]
[--model-name-suffix ]
[--model-package ]
[(-o | --output )]
[--release-note ] [--remove-operation-id-prefix]
[--reserved-words-mappings ...]
[(-s | --skip-overwrite)]
[(-t | --template-dir )]
[--type-mappings ...] [(-v | --verbose)]
OPTIONS
-a , --auth
adds authorization headers when fetching the swagger definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
...... (results omitted)
-v, --verbose
verbose mode يمكنك بعد ذلك تجميع العميل وتشغيله، بالإضافة إلى اختبارات الوحدة ضده:
عينات القرص المضغوط/العميل/متجر الحيوانات الأليفة/Java حزمة ام في ان
اللغات الأخرى لديها عينات من متاجر الحيوانات الأليفة أيضًا:
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
الأمر بنفس السهولة - فقط استخدم علامة -i للإشارة إلى خادم أو ملف.
؟ يأتي Swagger Codegen مع الكثير من المرونة لدعم تفضيلات إنشاء التعليمات البرمجية الخاصة بك. قم بمراجعة وثائق المولدات التي تأخذك عبر بعض الاحتمالات بالإضافة إلى عرض كيفية الإنشاء من الملفات المحلية وتجاهل تنسيقات الملفات.
قد لا ترغب في إنشاء كافة النماذج في مشروعك. وبالمثل قد ترغب في كتابة واحد أو اثنين فقط من واجهات برمجة التطبيقات. إذا كان الأمر كذلك، فتحقق من تعليمات الإنشاء الانتقائي.
هناك جوانب مختلفة لتخصيص منشئ الأكواد تتجاوز مجرد إنشاء القوالب أو تعديلها. تحتوي كل لغة على ملف تكوين داعم للتعامل مع تعيينات الأنواع المختلفة، أو إحضار النماذج الخاصة بك. لمزيد من المعلومات، راجع مستندات التكوين المتقدمة.
لديك خيارات. الأسهل هو استخدام أداة التحقق عبر الإنترنت الخاصة بنا والتي لن تسمح لك فقط بالتحقق من صحة مواصفاتك، ولكن باستخدام علامة تصحيح الأخطاء، يمكنك معرفة الخطأ في مواصفاتك. على سبيل المثال، تحقق من Swagger Validator.
إذا كنت تريد التحقق من الصحة مباشرة على جهازك الخاص، فإن Spectral يعد خيارًا ممتازًا.
للقيام بذلك، ما عليك سوى استخدام علامة -l dynamic-html عند قراءة ملف المواصفات. يؤدي هذا إلى إنشاء وثائق HTML المتوفرة كتطبيق من صفحة واحدة مع AJAX. لعرض الوثائق:
عينات القرص المضغوط/dynamic-html/ تثبيت npm عقدة .
الذي يطلق خادم Node.js بحيث يكون لمكالمات AJAX مكان تذهب إليه.
للقيام بذلك، ما عليك سوى استخدام علامة -l html عند قراءة ملف المواصفات. يؤدي هذا إلى إنشاء ملف HTML واحد بسيط يحتوي على ملف CSS مضمن حتى تتمكن من إرساله كمرفق بريد إلكتروني، أو تحميله من نظام الملفات الخاص بك:
عينات القرص المضغوط/html/ افتح ملف Index.html
من الممكن الاستفادة من Swagger Codegen مباشرة ضمن سير عمل CI/CD المفضل لديك لتبسيط متطلبات الإنشاء التلقائي لديك. راجع دليل تكامل سير العمل للاطلاع على معلومات حول خيارات تكامل Maven وGradle وGitHub. ؟
إذا كنت لا ترغب في تشغيل واستضافة مثيل إنشاء التعليمات البرمجية الخاص بك، فراجع معلومات المولدات الخاصة بنا عبر الإنترنت.
يرجى الرجوع إلى هذه الصفحة
أعضاء فريق Swagger Codegen الأساسيون هم مساهمون يقدمون مساهمات كبيرة (مراجعة المشكلات، وإصلاح الأخطاء، وإجراء التحسينات، وما إلى ذلك) للمشروع على أساس منتظم.
يتحمل أعضاء الفريق الأساسي المسؤوليات التالية:
يوفر التوجيه والتوجيه للمستخدمين الآخرين
مراجعة طلبات السحب والقضايا
يعمل على تحسين المولد عن طريق إجراء التحسينات أو إصلاح الأخطاء أو تحديث الوثائق
يضبط الاتجاه الفني للمولد
يرجى الكشف عن أي مشكلات أو نقاط ضعف متعلقة بالأمان عن طريق إرسال بريد إلكتروني إلى [email protected]، بدلاً من استخدام أداة تعقب المشكلات العامة.
يهدف مشروع Swagger Codegen إلى تقديم فائدة لمستخدمي مواصفات Swagger / Open API. المشروع نفسه لديه الترخيص كما هو محدد. بالإضافة إلى ذلك، يرجى فهم النقاط التالية:
تخضع القوالب المضمنة في هذا المشروع للترخيص.
لا يخضع الكود الذي تم إنشاؤه عمدًا لترخيص المشروع الأصلي
عندما يتم إنشاء التعليمات البرمجية من هذا المشروع، يجب اعتبارها كما هي ومملوكة لمستخدم البرنامج. لا توجد أي ضمانات - صريحة أو ضمنية - للتعليمات البرمجية التي تم إنشاؤها. يمكنك أن تفعل به ما يحلو لك، وبمجرد إنشائه، يصبح الكود مسؤوليتك ويخضع لشروط الترخيص التي تراها مناسبة.
نود أن نوجه تحية كبيرة لكل من ساهم في Swagger Codegen، سواء كان ذلك من خلال إثارة المشكلات أو إصلاح الأخطاء أو تأليف القوالب أو صياغة محتوى مفيد ليستفيد منه الآخرون.
