swagger editor
v4.14.0 Released!
⏰️ Mencari Swagger Editor versi generasi berikutnya?
SwaggerEditor kini dirilis di bawah dua saluran rilis utama:
Hanya SwaggerEditor@5 yang mendukung OpenAPI 3.1.0. SwaggerEditor@4 tidak akan menerima dukungan OpenAPI 3.1.0 dan saat ini dianggap sebagai warisan. Rencananya adalah untuk terus bermigrasi sepenuhnya ke SwaggerEditor@5 dan menghentikan penggunaan SwaggerEditor@4 di masa mendatang.
?️ Mencari Swagger Editor versi lama? Lihat cabang 2.x atau 3.x.
Swagger Editor memungkinkan Anda mengedit definisi OpenAPI API (OpenAPI 2.0 dan OpenAPI 3.0.3) dalam format JSON atau YAML di dalam browser Anda dan melihat dokumentasi secara real-time. Definisi OpenAPI yang valid kemudian dapat dibuat dan digunakan dengan alat Swagger lengkap (pembuatan kode, dokumentasi, dll).
Sebagai versi baru, yang ditulis dari awal, ada beberapa masalah umum dan fitur yang belum diterapkan. Lihat bagian Masalah Umum untuk lebih jelasnya.
Repositori ini diterbitkan ke dua modul NPM yang berbeda:
Jika Anda membuat aplikasi satu halaman, sangat disarankan menggunakan swagger-editor , karena swagger-editor-dist jauh lebih besar.
Swagger Editor menggunakan Scarf untuk mengumpulkan analisis instalasi anonim. Analitik ini membantu mendukung pengelola perpustakaan ini dan HANYA dijalankan selama instalasi. Untuk memilih tidak ikut serta, Anda dapat menyetel bidang scarfSettings.enabled ke false di package.json proyek Anda:
// package.json
{
// ...
"scarfSettings": {
"enabled": false
}
// ...
}
Alternatifnya, Anda dapat mengatur variabel lingkungan SCARF_ANALYTICS ke false sebagai bagian dari lingkungan yang menginstal paket npm Anda, misalnya SCARF_ANALYTICS=false npm install .
Salah satu skrip di bawah ini dapat dijalankan dengan mengetikkan npm run <script name> di direktori root proyek.
| Nama skrip | Keterangan |
|---|---|
dev | Memunculkan server dev yang memuat ulang panas pada port 3200. |
deps-check | Hasilkan laporan ukuran dan lisensi tentang ketergantungan Editor Swagger. |
lint | Laporkan kesalahan dan peringatan gaya ESLint. |
lint-errors | Laporkan kesalahan gaya ESLint, tanpa peringatan. |
lint-fix | Cobalah untuk memperbaiki kesalahan gaya secara otomatis. |
watch | Bangun kembali file inti di /dist ketika kode sumber berubah. Berguna untuk npm link . |
| Nama skrip | Keterangan |
|---|---|
build | Bangun kumpulan aset JS dan CSS baru, dan keluarkan ke /dist . |
build:bundle | Bangun hanya swagger-editor-bundle.js (commonJS). |
build:core | Bangun swagger-editor.(js|css) saja (commonJS). |
build:standalone | Bangun hanya swagger-editor-standalone-preset.js (commonJS). |
build:stylesheets | Bangun swagger-editor.css saja. |
build:es:bundle | Bangun hanya swagger-editor-es-bundle.js (es2015). |
build:es:bundle:core | Bangun hanya swagger-editor-es-bundle-core.js (es2015). |
| Nama skrip | Keterangan |
|---|---|
test | Jalankan pengujian unit di Node, jalankan pengujian end-to-end Cypress, dan jalankan ESLint dalam mode hanya kesalahan. |
test:unit-mocha | Jalankan pengujian unit berbasis Mocha di Node.js. |
test:unit-jest | Jalankan pengujian unit berbasis Jest di Node.js. |
e2e | Jalankan pengujian browser menyeluruh dengan Cypress. |
lint | Jalankan tes ESLint |
test:artifact | Jalankan daftar pengujian artefak bundel di Jest |
test:artifact:umd:bundle | Jalankan pengujian unit yang mengonfirmasi ekspor swagger-editor-bundle sebagai Fungsi |
test:artifact:es:bundle | Jalankan pengujian unit yang mengonfirmasi ekspor swagger-editor-es-bundle sebagai Fungsi |
test:artifact:es:bundle:core | Jalankan pengujian unit yang mengonfirmasi ekspor swagger-editor-es-bundle-core sebagai Fungsi |
$ npm i --legacy-peer-deps Jika Anda telah menginstal Node.js dan npm, Anda dapat menjalankan npm start untuk menjalankan server statis.
Jika tidak, Anda dapat membuka index.html langsung dari sistem file di browser Anda.
Jika Anda ingin membuat perubahan kode pada Swagger Editor, Anda dapat memulai server dev hot-reload Webpack melalui npm run dev .
Swagger Editor berfungsi di versi terbaru Chrome, Safari, Firefox, dan Edge.
Untuk membantu migrasi, berikut adalah masalah yang diketahui saat ini dengan 3.X. Daftar ini akan diperbarui secara berkala, dan tidak akan menyertakan fitur yang tidak diterapkan pada versi sebelumnya.
Ada gambar buruh pelabuhan yang diterbitkan di DockerHub.
Untuk menggunakan ini, jalankan perintah berikut:
docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor
Ini akan menjalankan Swagger Editor (dalam mode terpisah) pada port 80 di mesin Anda, sehingga Anda dapat membukanya dengan menavigasi ke http://localhost di browser Anda.
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor
json atau yaml Anda sendiri dari host lokal Anda: docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor
Catatan: Ketika variabel lingkungan URL dan SWAGGER_FILE disetel, URL memiliki prioritas dan SWAGGER_FILE diabaikan.
BASE_URL untuk mengakses aplikasi - misalnya jika Anda ingin aplikasi tersedia di http://localhost/swagger-editor/ : docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor
PORT untuk mengakses aplikasi, defaultnya adalah 8080 . docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor
GTM untuk melacak penggunaan editor angkuh. docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor
Anda juga dapat menyesuaikan berbagai titik akhir yang digunakan oleh Editor Swagger dengan variabel lingkungan berikut. Misalnya, ini bisa berguna jika Anda memiliki server generator Swagger sendiri:
| Variabel lingkungan | Nilai bawaan |
|---|---|
URL_SWAGGER2_GENERATOR | https://generator.swagger.io/api/swagger.json |
URL_OAS3_GENERATOR | https://generator3.swagger.io/openapi.json |
URL_SWAGGER2_CONVERTER | https://converter.swagger.io/api/convert |
Jika Anda ingin menjalankan Editor Swagger secara lokal tanpa fitur Codegen (Hasilkan Server dan Hasilkan Klien), Anda dapat mengatur variabel lingkungan di atas ke null ( URL_SWAGGER2_CONVERTER=null ).
Untuk membuat dan menjalankan image buruh pelabuhan dengan kode yang diperiksa di mesin Anda, jalankan perintah berikut dari direktori root proyek:
# Install npm packages (if needed)
npm install
# Build the app
npm run build
# Build an image
docker build -t swagger-editor .
# Run the container
docker run -d -p 80:8080 swagger-editor
Anda kemudian dapat melihat aplikasi dengan menavigasi ke http://localhost di browser Anda.
Mengimpor dokumen OpenAPI Anda
Berkontribusi
Penting
Pada versi yang lebih lama kami secara khusus merujuk pada React >=17 <18 .
Secara default, paket npm swagger-editor@4 hadir dengan versi terbaru React@18. Dimungkinkan untuk menggunakan paket swagger-editor@4 npm dengan React versi lama.
Katakanlah aplikasi saya terintegrasi dengan paket swagger-editor@4 npm dan menggunakan [email protected].
Untuk memberi tahu paket npm swagger-editor@4 bahwa saya memerlukannya untuk menggunakan versi React saya, saya perlu menggunakan npm override.
{
"dependencies" : {
"react" : " =17.0.2 " ,
"react-dom" : " =17.0.2 "
},
"overrides" : {
"swagger-editor" : {
"react" : " $react " ,
"react" : " $react-dom " ,
"react-redux" : " ^8 "
}
}
}Catatan
Override React dan ReactDOM didefinisikan sebagai referensi ke ketergantungan. Karena react-redux@9 hanya mendukung React >= 18 , kita perlu menggunakan react-redux@8 .
Untuk memberi tahu paket swagger-editor@4 npm bahwa saya memerlukannya untuk menggunakan versi React spesifik saya, saya perlu menggunakan resolusi benang.
{
"dependencies" : {
"react" : " 17.0.2 " ,
"react-dom" : " 17.0.2 "
},
"resolutions" : {
"swagger-editor/react" : " 17.0.2 " ,
"swagger-editor/react-dom" : " 17.0.2 " ,
"swagger-editor/react-redux" : " ^8 "
}
}Catatan
Resolusi React dan ReactDOM tidak dapat didefinisikan sebagai referensi terhadap ketergantungan. Sayangnya benang tidak mendukung aliasing seperti $react atau $react-dom seperti yang dilakukan npm . Anda harus menentukan versi persisnya.
Harap ungkapkan masalah atau kerentanan terkait keamanan apa pun dengan mengirim email ke [email protected], alih-alih menggunakan pelacak masalah publik.
