openapi json schema generator
4.5.1
قم بإنشاء SDK عميل من مستند OpenAPI 3.0.0-3.1.0 باستخدام مولد مخطط Openapi JSON. هذا المشروع هو مولد رمز يركز على دعم جميع ميزات مخطط OpenAPI و JSON.
يسمح مولد مخطط Openapi JSON بالتوليد التلقائي لمكتبات عملاء API (Generation SDK) إعطاء مستند OpenAPI (3.0.0-3.1.0* مدعوم). يركز هذا المشروع على جعل الإخراج متوافقًا بنسبة 100 ٪ مع مواصفات مخطط OpenAPI + JSON. الهدف من ذلك هو دعم كل شيء محدد في OpenAPI + مواصفات مخطط JSON المضمنة حتى يتمكن المطورون من استخدام جميع هذه الميزات.
حاليًا ، يتم دعم اللغات/الأطر التالية:
| ميزة | بيثون | جافا | كوتلين |
|---|---|---|---|
| حالة المولد | مستقر | مستقر | مستقر |
| Openapi v3.0.0-3.1.0 الابتلاع | x | x | x |
| JSON SCHEMA 2020-12 دعم (المكونات/المخططات) | x | x | x |
| فئات مخطط المكونات + الوثائق المنتجة | x | x | x |
| الوثائق التي تم إنتاجها لأنواع المكونات الأخرى: الرؤوس ، المعلمات ، أجسام الطلب ، ressponses ، SecuritySchemes | x | x | |
| الأساليب التي تم إنشاؤها لنقاط النهاية التي ترسل/استلام مستندات JSON + تم إنشاؤها لهم | x | x |
from ، 1var ، hi-there وما إلى ذلك فينستخدم خادم Discord كمكان لطرح الأسئلة ومساعدة بعضنا البعض. إنه يوفر وظائف مشابهة جدًا للركود. يمكنك الانضمام إلينا هنا: https://discord.gg/mhb8wequyq
نعم؛ المساهمات مرحب بها! أرسل العلاقات العامة إذا كنت ترغب في إضافة سقالة خادم جديدة أو عميل SDK أو مولد توثيق بأي لغة.
خضعت لمواصفات OpenAPI 3 مراجعات منذ الإنشاء الأولي في عام 2010. يحتوي مشروع OpenAPI-JSON-SCHEMA على التوافق التالي مع مواصفات OpenAPI:
| نسخة مولد مخطط Openapi JSON | توافق المواصفات Openapi |
|---|---|
| 3.3.0+ | 3.0.0 - 3.1.0* |
| 3.1.0 - 3.2.1 | 3.0.0 - 3.1.0 |
| 1.0.0 - 3.0.0 | 3.0.0 - 3.0.3 |
يتضمن دعم المواصفات Openapi v3.1.0 هذه الكلمات الرئيسية الجديدة/المحدثة من 2020-12 JSON Schema:
ملاحظة: يمكن أيضًا رؤية هذه الميزات في ميزات مخطط وثائق المولد
للبناء من المصدر ، تحتاج إلى تثبيت ومتوفر في $PATH:
جافا 11
Apache Maven 3.9.3 أو أكثر
بعد استنساخ المشروع ، يمكنك بنائه من المصدر باستخدام هذا الأمر:
mvn clean install يحتوي البناء الافتراضي على الحد الأدنى من التحليل الثابت (عبر CheckStyle). لتشغيل بنيتك باستخدام PMD و Spotbugs ، استخدم ملف تعريف static-analysis :
mvn -Pstatic-analysis clean installتعمل صورة Docker باعتبارها قابلة للتنفيذ قائمة بذاتها. يمكن استخدامه كبديل للتثبيت عبر Homebrew ، أو للمطورين الذين لا يستطيعون تثبيت Java أو ترقية الإصدار المثبت.
لإنشاء رمز باستخدام هذه الصورة ، ستحتاج إلى تركيب موقع محلي كمعول حجم.
مثال:
docker run --rm -v " ${PWD} :/local " openapijsonschematools/openapi-json-schema-generator-cli generate
-i https://raw.githubusercontent.com/openapi-json-schema-tools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml
-g python
-o /local/out/python سيتم تحديد الكود الذي تم إنشاؤه تحت ./out/python في الدليل الحالي.
يمكنك استخدام bin/run-in-docker.sh للقيام بكل التطوير. يقوم هذا البرنامج النصي بتخطيط مستودعك المحلي إلى /gen في حاوية Docker. كما أنه يقوم بتعيين ~/.m2/repository إلى موقع الحاوية المناسب.
لتنفيذ mvn package :
git clone https://github.com/openapi-json-schema-tools/openapi-json-schema-generator
cd openapi-json-schema-generator
./bin/run-in-docker.sh mvn packageيمكن الآن الوصول إلى القطع الأثرية في دليل العمل الخاص بك.
بمجرد إنشائها ، سيكون run-in-docker.sh بمثابة تنفيذ لـ OpenAPI-JSON-SCHEMA-CLI-CLI. لإنشاء رمز ، ستحتاج إلى الإخراج إلى دليل تحت /gen (على سبيل المثال /gen/out ). على سبيل المثال:
./bin/run-in-docker.sh help # Executes 'help' command for openapi-json-schema-generator-cli
./bin/run-in-docker.sh list # Executes 'list' command for openapi-json-schema-generator-cli
./bin/run-in-docker.sh /gen/bin/python-petstore.sh # Builds the Python client
./bin/run-in-docker.sh generate -i src/test/resources/3_0/petstore.yaml
-g go -o /gen/out/python-petstore -p packageName=petstore_api # generates python client, outputs locally to ./out/python-petstore في حالة حدوث خطأ كهذا ، فقط قم بتنفيذ أمر تثبيت MVN Clean -U :
org.apache.maven.lifecycle.lifecycleexecutionexception: فشل في تنفيذ الهدف org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: اختبار (اختبار الافتراضي) على مشروع Openapi-json: org.apache.maven.plugins: Maven-Surefire-Plugin: 2.19.1: الاختبار: java.lang.exceptionInitializerError
./run-in-docker.sh mvn clean install -Uفشل تنفيذ الهدف org.fortasoft: Gradle-Maven-Plugin: 1.0.8: استدعاء (افتراضي) على المشروع Openapi-json-shema-generator-plugin-mvn-wrapper: org.gradle.tooling.buildexception: 'https://services.gradle.org/distributions/gradle-4.7-bin.zip'
الآن: لا يوجد حل لهذا واحد: |
لإنشاء عميل Python لـ petstore.yaml ، يرجى تشغيل ما يلي
git clone https://github.com/openapi-json-schema-tools/openapi-json-schema-generator
cd openapi-json-schema-generator
mvn clean package
java -jar target/openapi-json-schema-generator-cli.jar generate
-i https://raw.githubusercontent.com/openapi-json-schema-tools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml
-g python
-o /var/tmp/python_api_client (إذا كنت على Windows ، استبدل الأمر الأخير بـ java -jar targetopenapi-json-schema-generator-cli.jar generate -i https://raw.githubusercontent.com/openapi-json-schema-tools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml -g python -oc:temppython_api_client )
للحصول على قائمة بالخيارات العامة المتاحة ، يرجى تشغيل java -jar target/openapi-json-schema-generator-cli.jar help generate
للحصول على قائمة بالخيارات المحددة Python (والتي يمكن تمريرها إلى المولد مع ملف تكوين عبر خيار -c ) ، يرجى تشغيل java -jar target/openapi-json-schema-generator-cli.jar config-help -g python
يمكنك بناء عميل ضد API petstore على النحو التالي:
./bin/generate-samples.sh ./bin/generate_samples_configs/python.yaml(على Windows ، يرجى تثبيت Git Bash لـ Windows لتشغيل الأمر أعلاه)
سيقوم هذا البرنامج النصي بتشغيل المولد مع هذا الأمر:
java -jar target/openapi-json-schema-generator-cli.jar generate
-i https://raw.githubusercontent.com/openapijsonschematools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml
-g python
-t src/main/resources/python
--additional-properties packageName=petstore_api
-o samples/client/petstore/pythonمع عدد من الخيارات. تم توثيق خيارات بيثون هنا.
يمكنك أيضًا الحصول على الخيارات باستخدام أمر help generate (أدناه يظهر فقط نتائج جزئية):
NAME
openapi-json-schema-generator-cli generate - Generate code with the specified
generator.
SYNOPSIS
openapi-json-schema-generator-cli generate
[(-a <authorization> | --auth <authorization>)]
[--api-name-suffix <api name suffix>] [--api-package <api package>]
[--artifact-id <artifact id>] [--artifact-version <artifact version>]
[(-c <configuration file> | --config <configuration file>)] [--dry-run]
[(-e <templating engine> | --engine <templating engine>)]
[--enable-post-process-file]
[(-g <generator name> | --generator-name <generator name>)]
[--git-host <git host>] [--git-repo-id <git repo id>]
[--git-user-id <git user id>] [--global-property <global properties>...]
[--group-id <group id>] [--hide-generation-timestamp]
[--http-user-agent <http user agent>]
[(-i <spec file> | --input-spec <spec file>)]
[--ignore-file-override <ignore file override location>]
[--ints-allowed-for-float-double-formats]
[--invoker-package <invoker package>] [--minimal-update]
[--model-name-prefix <model name prefix>]
[--model-name-suffix <model name suffix>]
[(-o <output directory> | --output <output directory>)] [(-p <additional properties> | --additional-properties <additional properties>)...]
[--package-name <package name>] [--release-note <release note>]
[--remove-enum-value-prefix] [--remove-operation-id-prefix]
[(-s | --skip-overwrite)] [--skip-operation-example]
[--skip-validate-spec] [--strict-spec <true/false strict behavior>]
[(-t <template directory> | --template-dir <template directory>)]
[(-v | --verbose)]
OPTIONS
-a <authorization>, --auth <authorization>
adds authorization headers when fetching the OpenAPI definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
--api-name-suffix <api name suffix>
Suffix that will be appended to all API names ('tags'). Default:
Api. e.g. Pet => PetApi. Note: Only ruby, python, jaxrs generators
support this feature at the moment.
--api-package <api package>
package for generated api classes
--artifact-id <artifact id>
artifactId in generated pom.xml. This also becomes part of the
generated library's filename
--artifact-version <artifact version>
artifact version in generated pom.xml. This also becomes part of the
generated library's filename
-c <configuration file>, --config <configuration file>
Path to configuration file. It can be JSON or YAML. If file is JSON,
the content should have the format {"optionKey":"optionValue",
"optionKey1":"optionValue1"...}. If file is YAML, the content should
have the format optionKey: optionValue. Supported options can be
different for each language. Run config-help -g {generator name}
command for language-specific config options.
--dry-run
Try things out and report on potential changes (without actually
making changes).
-e <templating engine>, --engine <templating engine>
templating engine: "handlebars"(default) or "mustache"
--enable-post-process-file
Enable post-processing file using environment variables.
-g <generator name>, --generator-name <generator name>
generator to use (see list command for list)
--git-host <git host>
Git host, e.g. gitlab.com.
--git-repo-id <git repo id>
Git repo ID, e.g. openapi-generator.
--git-user-id <git user id>
Git user ID, e.g. openapijsonschematools.
--global-property <global properties>
sets specified global properties (previously called 'system
properties') in the format of name=value,name=value (or multiple
options, each with name=value)
--group-id <group id>
groupId in generated pom.xml
--hide-generation-timestamp
Hides the generation timestamp when files are generated.
--http-user-agent <http user agent>
HTTP user agent, e.g. codegen_csharp_api_client, default to
'OpenAPI-Generator/{packageVersion}/{language}'
-i <spec file>, --input-spec <spec file>
location of the OpenAPI spec, as URL or file (required if not loaded
via config using -c)
--ignore-file-override <ignore file override location>
Specifies an override location for the .openapi-generator-ignore
file. Most useful on initial generation.
--ints-allowed-for-float-double-formats
Integers are allowed in for type: number format:float/double
payloads
--invoker-package <invoker package>
root package for generated code
--minimal-update
Only write output files that have changed.
--model-name-prefix <model name prefix>
Prefix that will be prepended to all model names.
--model-name-suffix <model name suffix>
Suffix that will be appended to all model names.
-o <output directory>, --output <output directory>
where to write the generated files (current dir by default)
-p <additional properties>, --additional-properties <additional
properties>
sets additional properties that can be referenced by the mustache
templates in the format of name=value,name=value. You can also have
multiple occurrences of this option.
--package-name <package name>
package for generated classes (where supported)
--release-note <release note>
Release note, default to 'Minor update'.
--remove-enum-value-prefix
Remove the common prefix of enum values
--remove-operation-id-prefix
Remove prefix of operationId, e.g. config_getId => getId
-s, --skip-overwrite
specifies if the existing files should be overwritten during the
generation.
--skip-operation-example
Skip examples defined in operations to avoid out of memory errors.
--skip-validate-spec
Skips the default behavior of validating an input specification.
--strict-spec <true/false strict behavior>
'MUST' and 'SHALL' wording in OpenAPI spec is strictly adhered to.
e.g. when false, no fixes will be applied to documents which pass
validation but don't follow the spec.
-t <template directory>, --template-dir <template directory>
folder containing the template files
-v, --verbose
verbose mode
يمكنك بعد ذلك استخدام العميل الذي تم إنشاؤه تلقائيًا. README.MD هي نقطة انطلاق جيدة.
المولدات الأخرى لديها عينات أيضا.
يرجى الرجوع إلى تخصيص. md حول كيفية تخصيص الإخراج (على سبيل المثال اسم الحزمة ، الإصدار)
يرجى الرجوع إلى integration.md حول كيفية دمج مولد OpenAPI مع Maven و Gradle و Github و CI/CD.
يهدف مشروع OpenAPI JSON Schema Generator كفائدة لمستخدمي مواصفات API المفتوحة. المشروع نفسه لديه الترخيص كما هو محدد. بالإضافة إلى ذلك ، يرجى فهم النقاط التالية:
عندما يتم إنشاء التعليمات البرمجية من هذا المشروع ، يجب اعتباره يملكه مستخدم البرنامج. لا توجد ضمانات-معبرة أو ضمنية-رمز تم إنشاؤه. يمكنك أن تفعل ما تتمناه به ، وبمجرد إنشاءه ، فإن الكود هو مسؤوليتك وتخضع لشروط الترخيص التي تراها مناسبة.
بحث رمز جيثب
يعتمد هذا الريبو على V6.2.0 من مولد OpenAPI. يركز هذا المشروع على جعل الإخراج متوافقًا بنسبة 100 ٪ مع مخطط JSON كجزء من مواصفات OpenAPI 3.1 مع التركيز على الحالات المعقدة (النهج من أعلى إلى أسفل). الهدف من ذلك هو دعم كل شيء محدد في مخطط JSON حتى يتمكن المطورون من الاستفادة من مخطط JSON وكذلك مواصفات OpenAPI في تصميم API الخاص بهم. يتيح البناء هنا الحصول على المزيد من التقدم السريع لدعم ميزات جديدة في OpenAPI 3.x دون الحاجة إلى دعم العديد من المولدات القديمة التي لا تستخدم الميزات الجديدة.
يعتمد مولد مخطط Openapi JSON على OpenAPI Generator V6.2.0. تم إنشاء المشروع هنا لأن فريق Openapi-Core Core يتطلب إزالة مولد Python من مشروعهم. فضل مؤلف كتاب Python Generator (spacether) الاستمرار في البناء في ريبو المولد Openapi ، لكن الفريق الأساسي رفض التفكير في الحفاظ على Python في Openapi-Cenerator. فيما يلي جدول زمني لتلك الأحداث وبعض أسبابها:
حقوق الطبع والنشر 2023 Openapi-json-Schema-Generator المساهمين حقوق الطبع والنشر 2018 مساهمات Openapi-Generator (https://openapi-generator.tech) حقوق الطبع والنشر 2018 Smartbear Software
مرخصة بموجب ترخيص Apache ، الإصدار 2.0 ("الترخيص") ؛ لا يجوز لك استخدام هذا الملف إلا في الامتثال للترخيص. يمكنك الحصول على نسخة من الترخيص على apache.org/licenses/license-2.0
ما لم يكن مطلوبًا بموجب القانون المعمول به أو الموافقة على الكتابة ، يتم توزيع البرامج الموزعة بموجب الترخيص على أساس "كما هي" ، دون ضمانات أو شروط من أي نوع ، إما صريحة أو ضمنية. راجع ترخيص الأذونات والقيود التي تحكم اللغة المحددة بموجب الترخيص.
