openapi json schema generator
4.5.1
Auto สร้างไคลเอนต์ SDK จากเอกสาร OpenAPI 3.0.0-3.1.0 ของคุณโดยใช้ OpenAPI JSON Schema Generator โครงการนี้เป็นเครื่องกำเนิดรหัสที่มุ่งเน้นไปที่การสนับสนุนคุณสมบัติ OpenAPI และ JSON SCHEMA ทั้งหมด
OpenAPI JSON Schema Generator ช่วยให้รุ่นอัตโนมัติของไลบรารีไคลเอนต์ API (การสร้าง SDK) ได้รับเอกสาร OpenAPI (3.0.0-3.1.0* รองรับ) โครงการนี้มุ่งเน้นไปที่การทำให้เอาต์พุตเป็นไปตามมาตรฐาน 100% ด้วยสเปค OpenAPI + JSON Schema เป้าหมายคือการสนับสนุนอย่างเต็มที่ทุกอย่างที่กำหนดไว้ใน OpenAPI + สเป็คสคีมา JSON ที่รวมอยู่เพื่อให้นักพัฒนาสามารถใช้คุณสมบัติทั้งหมดเหล่านั้นได้
ปัจจุบันสนับสนุนภาษา/เฟรมเวิร์กต่อไปนี้:
| คุณสมบัติ | งูหลาม | ชวา | Kotlin |
|---|---|---|---|
| สถานะเครื่องกำเนิดไฟฟ้า | มั่นคง | มั่นคง | มั่นคง |
| OpenAPI v3.0.0-3.1.0 การกลืนกิน | x | x | x |
| การสนับสนุน JSON SCHEMA 2020-12 (Components/Schemas) | x | x | x |
| คลาสสคีมาคลาส + เอกสารที่ผลิตขึ้น | x | x | x |
| เอกสารที่ผลิตสำหรับประเภทส่วนประกอบอื่น ๆ : ส่วนหัว, พารามิเตอร์, requestbodies, ressponses, securityschemes | x | x | |
| วิธีการที่สร้างขึ้นสำหรับจุดสิ้นสุด ที่ส่ง/รับเอกสาร JSON + ที่สร้างขึ้นสำหรับพวกเขา | x | x |
from , 1var , hi-there ฯลฯเราใช้เซิร์ฟเวอร์ Discord เป็นสถานที่ถามคำถามและช่วยเหลือซึ่งกันและกัน มันมีฟังก์ชันการทำงานคล้ายกับ Slack มาก คุณสามารถเข้าร่วมกับเราได้ที่นี่: https://discord.gg/mhb8wequyq
ใช่; ยินดีต้อนรับ! ส่ง PR หากคุณต้องการเพิ่มนั่งร้านเซิร์ฟเวอร์ใหม่ไคลเอนต์ SDK หรือตัวสร้างเอกสารในภาษาใด ๆ
ข้อมูลจำเพาะ OpenAPI ได้รับการแก้ไข 3 ตั้งแต่การสร้างครั้งแรกในปี 2010 โครงการ OpenAPI-JSON-SCHEMA-Generator มีความเข้ากันได้ดังต่อไปนี้กับข้อกำหนด OpenAPI:
| Openapi Json Schema Generator | ความเข้ากันได้ของ OpenAPI Spec |
|---|---|
| 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 รวมถึงคำหลักใหม่ของ JSON SCHEMA ใหม่/ปรับปรุงใหม่เหล่านี้:
หมายเหตุ: คุณสมบัติเหล่านี้ยังสามารถเห็นได้ในคุณสมบัติสคีมาเอกสารของเครื่องกำเนิดไฟฟ้า
ในการสร้างจากแหล่งที่มาคุณต้องติดตั้งและมีอยู่ใน $PATH:
Java 11
Apache Maven 3.9.3 หรือมากกว่า
หลังจากโคลนนิ่งโครงการคุณสามารถสร้างจากแหล่งที่มาด้วยคำสั่งนี้:
mvn clean install บิลด์เริ่มต้นมีการวิเคราะห์แบบคงที่น้อยที่สุด (ผ่าน CheckStyle) ในการเรียกใช้งานสร้างของคุณด้วย PMD และ SpotBugs ให้ใช้โปรไฟล์ static-analysis :
mvn -Pstatic-analysis clean installภาพนักเทียบท่าทำหน้าที่เป็นแบบสแตนด์อโลน สามารถใช้เป็นทางเลือกในการติดตั้งผ่าน 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 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-Generator-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 Install -U :
org.apache.maven.lifecycle.lifecycleexecutionexception: ล้มเหลวในการดำเนินการเป้าหมาย org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: ทดสอบ (ทดสอบเริ่มต้น) ในโครงการ openapi-json-schema-generator: ความไม่ลงรอยกันประเภทเกิดขึ้น org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: การทดสอบ: java.lang.exceptioniniNitializerRor
./run-in-docker.sh mvn clean install -Uล้มเหลวในการดำเนินการเป้าหมาย org.fortasoft: Gradle-Maven-Plugin: 1.0.8: เรียกใช้ (ค่าเริ่มต้น) ในโครงการ OpenApi-Json-Schema-Generator-Gradle-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
คุณสามารถสร้างลูกค้ากับ Petstore API ดังนี้:
./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มีตัวเลือกมากมาย ตัวเลือก 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 มีวัตถุประสงค์เพื่อเป็นประโยชน์สำหรับผู้ใช้ข้อมูลจำเพาะ Open API โครงการมีใบอนุญาตตามที่ระบุไว้ นอกจากนี้โปรดเข้าใจประเด็นต่อไปนี้:
เมื่อรหัสถูกสร้างขึ้นจากโครงการนี้จะต้องได้รับการพิจารณา ว่าเป็น และเป็นเจ้าของโดยผู้ใช้ซอฟต์แวร์ ไม่มีการรับประกัน-แสดงออกหรือโดยนัย-สำหรับรหัสที่สร้างขึ้น คุณสามารถทำสิ่งที่คุณต้องการได้และเมื่อสร้างขึ้นรหัสคือความรับผิดชอบของคุณและอยู่ภายใต้ข้อกำหนดการออกใบอนุญาตที่คุณเห็นว่าเหมาะสม
การค้นหารหัส GitHub
repo นี้ขึ้นอยู่กับ v6.2.0 ของเครื่องกำเนิด OpenAPI โครงการนี้มุ่งเน้นไปที่การทำให้เอาต์พุตเป็นไปตามมาตรฐาน 100% ด้วย JSON Schema ซึ่งเป็นส่วนหนึ่งของข้อกำหนด OpenAPI 3.1 โดยมุ่งเน้นที่กรณีที่ซับซ้อน (วิธีการจากบนลงล่าง) เป้าหมายคือการสนับสนุนทุกอย่างที่กำหนดไว้ใน JSON Schema อย่างเต็มที่เพื่อให้นักพัฒนาสามารถใช้ประโยชน์จากสคีมา JSON รวมถึงข้อกำหนด OpenAPI ในการออกแบบ API ของพวกเขา การสร้างที่นี่ช่วยให้ความคืบหน้าอย่างรวดเร็วยิ่งขึ้นรองรับคุณสมบัติใหม่ใน OpenAPI 3.X โดยไม่ต้องรองรับเครื่องกำเนิดไฟฟ้ารุ่นเก่าจำนวนมากซึ่งไม่ได้ใช้คุณสมบัติใหม่
OpenAPI JSON Schema Generator ขึ้นอยู่กับ OpenAPI Generator V6.2.0 โครงการถูกสร้างขึ้นที่นี่เนื่องจากทีม Core OpenApi-Generator ต้องการการกำจัดเครื่องกำเนิด Python ออกจากโครงการของพวกเขา ผู้เขียน The Python Generator (@spacether) ต้องการสร้างการสร้างใน repo openapi-generator แต่ทีมหลักปฏิเสธที่จะพิจารณาการรักษา Python ใน Openapi-Generator ด้านล่างนี้เป็นไทม์ไลน์ของเหตุการณ์เหล่านั้นและเหตุผลบางประการ:
Copyright 2023 OpenApi-Json-Schema-Generator ผู้มีส่วนร่วมลิขสิทธิ์ 2018 OpenApi-Generator (https://openapi-generator.tech) ซอฟต์แวร์ลิขสิทธิ์ 2018 Smartbear
ได้รับใบอนุญาตภายใต้ใบอนุญาต Apache เวอร์ชัน 2.0 ("ใบอนุญาต"); คุณไม่สามารถใช้ไฟล์นี้ยกเว้นตามใบอนุญาต คุณอาจได้รับสำเนาใบอนุญาตที่ apache.org/licenses/license-2.0
เว้นแต่ว่ากฎหมายที่บังคับใช้หรือตกลงเป็นลายลักษณ์อักษรซอฟต์แวร์ที่แจกจ่ายภายใต้ใบอนุญาตจะถูกแจกจ่ายตาม "ตามพื้นฐาน" โดยไม่มีการรับประกันหรือเงื่อนไขใด ๆ ไม่ว่าจะโดยชัดแจ้งหรือโดยนัย ดูใบอนุญาตสำหรับภาษาเฉพาะที่ควบคุมการอนุญาตและข้อ จำกัด ภายใต้ใบอนุญาต
