openapi json schema generator
4.5.1
Auto menghasilkan SDK klien dari dokumen OpenAPI 3.0.0-3.1.0 Anda menggunakan OpenAPI JSON Schema Generator. Proyek ini adalah generator kode yang berfokus pada mendukung semua fitur OpenAPI dan JSON Skema.
Generator Skema OpenAPI JSON memungkinkan generasi otomatis perpustakaan klien API (generasi SDK) yang diberikan dokumen OpenAPI (3.0.0-3.1.0* didukung). Proyek ini berfokus pada membuat output 100% sesuai dengan spesifikasi skema OpenAPI + JSON. Tujuannya adalah untuk sepenuhnya mendukung semua yang didefinisikan dalam openapi + spesifikasi skema JSON yang disertakan sehingga pengembang dapat menggunakan semua fitur tersebut.
Saat ini, bahasa/kerangka kerja berikut didukung:
| Fitur | Python | Jawa | Kotlin |
|---|---|---|---|
| Status generator | stabil | stabil | stabil |
| Openapi v3.0.0-3.1.0 konsumsi | X | X | X |
| JSON Schema 2020-12 Dukungan (komponen/skema) | X | X | X |
| Kelas Skema Komponen + Dokumentasi yang Diproduksi | X | X | X |
| Dokumentasi yang diproduksi untuk jenis komponen lainnya: header, parameter, requestbodies, ressponses, securityschemes | X | X | |
| Metode yang dihasilkan untuk titik akhir yang mengirim/menerima json + dokumen yang dihasilkan untuk mereka | X | X |
from , 1var , hi-there dll diKami menggunakan server Discord sebagai tempat untuk mengajukan pertanyaan dan saling membantu. Ini menawarkan fungsionalitas yang sangat mirip dengan Slack. Anda dapat bergabung dengan kami di sini: https://discord.gg/mhb8wequyq
Ya; Kontribusi dipersilakan! Kirim PR jika Anda ingin menambahkan perancah server baru, SDK klien, atau generator dokumentasi dalam bahasa apa pun.
Spesifikasi OpenAPI telah mengalami 3 revisi sejak pembuatan awal pada tahun 2010. Proyek OpenAPI-JSON-Schema-Generator memiliki kompatibilitas berikut dengan spesifikasi OpenAPI:
| Versi Generator Skema OpenAPI JSON | Kompatibilitas Spesifikasi 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 Dukungan Spesifikasi Termasuk Kata Kunci Skema JSON 2020-12 yang baru/diperbarui ini:
Catatan: Fitur -fitur ini juga dapat dilihat dalam fitur skema dokumentasi generator
Untuk membangun dari sumber, Anda perlu yang diinstal berikut dan tersedia di $PATH:
Java 11
Apache Maven 3.9.3 atau lebih
Setelah mengkloning proyek, Anda dapat membangunnya dari sumber dengan perintah ini:
mvn clean install Bangunan default berisi analisis statis minimal (melalui checkstyle). Untuk menjalankan build Anda dengan PMD dan Spotbugs, gunakan profil static-analysis :
mvn -Pstatic-analysis clean installGambar Docker bertindak sebagai yang mandiri dieksekusi. Ini dapat digunakan sebagai alternatif untuk menginstal melalui homebrew, atau untuk pengembang yang tidak dapat menginstal Java atau meningkatkan versi yang diinstal.
Untuk menghasilkan kode dengan gambar ini, Anda harus memasang lokasi lokal sebagai volume.
Contoh:
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 Kode yang dihasilkan akan ditempatkan di bawah ./out/python di direktori saat ini.
Anda dapat menggunakan bin/run-in-docker.sh untuk melakukan semua pengembangan. Skrip ini memetakan repositori lokal Anda ke /gen di wadah Docker. Ini juga memetakan ~/.m2/repository ke lokasi wadah yang sesuai.
Untuk mengeksekusi 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 packageBangun artefak sekarang dapat diakses di direktori kerja Anda.
Setelah dibangun, run-in-docker.sh akan bertindak sebagai yang dapat dieksekusi untuk Openapi-json-Schema-Generator-Cli. Untuk menghasilkan kode, Anda harus mengeluarkan output ke direktori di bawah /gen (misalnya /gen/out ). Misalnya:
./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 Jika kesalahan seperti ini terjadi, cukup jalankan perintah pemasangan mvn clean -u :
org.apache.maven.lifecycle.lifecycleExecutionException: Gagal melaksanakan sasaran org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: tes (default-test) pada proyek Openapi-json-schema-generator: Sebuah inkompatibilitas tipe sementara sementara waktu yang dikompatibilitas sementara waktu yang terjadi sementara waktu sementara waktu terjadi kompatibilitas sementara waktu. org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: tes: java.lang.exceptioninitializerError tidak dapat dilemparkan ke java.io.ioexception
./run-in-docker.sh mvn clean install -UGagal melaksanakan gol org.fortasoft: gradle-maven-plugin: 1.0.8: Invoke (default) pada proyek Openapi-json-Schema-generator-gradle-plugin-mvn-wrapper: org.gradle.tooling.buildException: Tidak dapat mengeksekusi pembangunan menggunakan gradle gradle. 'https://services.gradle.org/distributions/gradle-4.7-bin.zip'
Saat ini: tidak ada solusi untuk yang satu ini: |
Untuk menghasilkan klien Python untuk Petstore.yaml, silakan jalankan berikut ini
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 (Jika Anda berada di windows, ganti perintah terakhir dengan 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 )
Untuk mendapatkan daftar opsi umum yang tersedia, silakan jalankan java -jar target/openapi-json-schema-generator-cli.jar help generate
Untuk mendapatkan daftar opsi yang ditentukan Python (yang dapat diteruskan ke generator dengan file konfigurasi melalui opsi -c ), silakan jalankan java -jar target/openapi-json-schema-generator-cli.jar config-help -g python
Anda dapat membangun klien terhadap API Petstore sebagai berikut:
./bin/generate-samples.sh ./bin/generate_samples_configs/python.yaml(Di Windows, silakan instal Git Bash untuk Windows untuk menjalankan perintah di atas)
Script ini akan menjalankan generator dengan perintah ini:
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/pythondengan sejumlah opsi. Opsi Python didokumentasikan di sini.
Anda juga bisa mendapatkan opsi dengan perintah help generate (di bawah hanya menunjukkan hasil parsial):
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
Anda kemudian dapat menggunakan klien yang dihasilkan otomatis. README.MD adalah titik awal yang baik.
Generator lain juga memiliki sampel.
Silakan merujuk ke kustomisasi.md tentang cara menyesuaikan output (misalnya nama paket, versi)
Silakan merujuk ke Integration.md tentang cara mengintegrasikan generator openapi dengan Maven, Gradle, GitHub dan CI/CD.
Proyek Generator Skema OpenAPI JSON dimaksudkan sebagai manfaat bagi pengguna spesifikasi API terbuka. Proyek itu sendiri memiliki lisensi seperti yang ditentukan. Selain itu, harap pahami poin -poin berikut:
Ketika kode dihasilkan dari proyek ini, itu harus dianggap sebagaimana adanya dan dimiliki oleh pengguna perangkat lunak. Tidak ada jaminan-terungkap atau tersirat-untuk kode yang dihasilkan. Anda dapat melakukan apa yang Anda inginkan dengannya, dan sekali dihasilkan, kode adalah tanggung jawab Anda dan tunduk pada persyaratan lisensi yang Anda anggap sesuai.
Pencarian Kode GitHub
Repo ini didasarkan pada V6.2.0 dari OpenAPI Generator. Proyek ini berfokus pada membuat output 100% sesuai dengan skema JSON sebagai bagian dari spesifikasi OpenAPI 3.1 dengan fokus pada kasus kompleks (pendekatan top-down). Tujuannya adalah untuk sepenuhnya mendukung segala sesuatu yang didefinisikan dalam skema JSON sehingga pengembang dapat memanfaatkan skema JSON serta spesifikasi openapi dalam desain API mereka. Membangun di sini memungkinkan kemajuan yang lebih cepat mendukung fitur -fitur baru di OpenAPI 3.x tanpa harus mendukung banyak generator lama yang tidak menggunakan fitur baru.
OpenAPI JSON Schema Generator didasarkan pada OpenAPI Generator v6.2.0. Proyek ini dibuat di sini karena tim inti OpenAPI-generator mengharuskan penghapusan generator Python dari proyek mereka. Penulis generator Python (@spacether) lebih suka terus membangun dalam repo OpenAPI generator, tetapi tim inti menolak untuk mempertimbangkan menjaga Python di OpenAPI generator. Di bawah ini adalah garis waktu dari peristiwa tersebut dan beberapa alasan mereka:
Hak Cipta 2023 Kontributor OpenAPI-JSON-SCHEMA-generator Hak Cipta 2018 Kontributor OpenAPi-Generator (https://openapi-generator.tech) Hak Cipta 2018 Smartbear Software
Berlisensi di bawah lisensi Apache, versi 2.0 ("lisensi"); Anda tidak boleh menggunakan file ini kecuali sesuai dengan lisensi. Anda dapat memperoleh salinan lisensi di apache.org/licenses/license-2.0
Kecuali diharuskan oleh hukum yang berlaku atau disepakati secara tertulis, perangkat lunak yang didistribusikan di bawah lisensi didistribusikan berdasarkan "sebagaimana adanya", tanpa jaminan atau ketentuan dalam bentuk apa pun, baik tersurat maupun tersirat. Lihat lisensi untuk bahasa spesifik yang mengatur izin dan batasan di bawah lisensi.
