swagger editor
v4.14.0 Released!
⏰️ Vous recherchez la version nouvelle génération de Swagger Editor ?
SwaggerEditor est désormais publié sous deux canaux de publication principaux :
Seul SwaggerEditor@5 prend en charge OpenAPI 3.1.0. SwaggerEditor@4 ne bénéficiera pas du support OpenAPI 3.1.0 et est considéré comme un héritage à ce stade. Le plan est de migrer continuellement et entièrement vers SwaggerEditor@5 et de rendre SwaggerEditor@4 obsolète à l'avenir.
?️ Vous recherchez l’ancienne version de Swagger Editor ? Reportez-vous aux branches 2.x ou 3.x.
Swagger Editor vous permet de modifier les définitions de l'API OpenAPI (OpenAPI 2.0 et OpenAPI 3.0.3) au format JSON ou YAML dans votre navigateur et de prévisualiser les documentations en temps réel. Des définitions OpenAPI valides peuvent ensuite être générées et utilisées avec l'ensemble des outils Swagger (génération de code, documentation, etc.).
En tant que toute nouvelle version, écrite de A à Z, il existe des problèmes connus et des fonctionnalités non implémentées. Consultez la section Problèmes connus pour plus de détails.
Ce référentiel publie sur deux modules NPM différents :
Si vous créez une application d'une seule page, l'utilisation swagger-editor est fortement recommandée, car swagger-editor-dist est nettement plus grande.
Swagger Editor utilise Scarf pour collecter des analyses d'installation anonymisées. Ces analyses aident à prendre en charge les responsables de cette bibliothèque et s'exécutent UNIQUEMENT pendant l'installation. Pour vous désinscrire, vous pouvez définir le champ scarfSettings.enabled sur false dans package.json de votre projet :
// package.json
{
// ...
"scarfSettings": {
"enabled": false
}
// ...
}
Alternativement, vous pouvez définir la variable d'environnement SCARF_ANALYTICS sur false dans le cadre de l'environnement qui installe vos packages npm, par exemple, SCARF_ANALYTICS=false npm install .
N'importe lequel des scripts ci-dessous peut être exécuté en tapant npm run <script name> dans le répertoire racine du projet.
| Nom du script | Description |
|---|---|
dev | Générez un serveur de développement à rechargement à chaud sur le port 3200. |
deps-check | Générez un rapport sur la taille et les licences des dépendances de Swagger Editors. |
lint | Signalez les erreurs et les avertissements de style ESLint. |
lint-errors | Signalez les erreurs de style ESLint, sans avertissement. |
lint-fix | Essayez de corriger automatiquement les erreurs de style. |
watch | Reconstruisez les fichiers principaux dans /dist lorsque le code source change. Utile pour npm link . |
| Nom du script | Description |
|---|---|
build | Créez un nouvel ensemble d'actifs JS et CSS et exportez-les vers /dist . |
build:bundle | Construisez swagger-editor-bundle.js uniquement (commonJS). |
build:core | Construisez swagger-editor.(js|css) uniquement (commonJS). |
build:standalone | Créez uniquement swagger-editor-standalone-preset.js (commonJS). |
build:stylesheets | Construisez uniquement swagger-editor.css . |
build:es:bundle | Construisez swagger-editor-es-bundle.js uniquement (es2015). |
build:es:bundle:core | Créez uniquement swagger-editor-es-bundle-core.js (es2015). |
| Nom du script | Description |
|---|---|
test | Exécutez des tests unitaires dans Node, exécutez des tests Cypress de bout en bout et exécutez ESLint en mode erreurs uniquement. |
test:unit-mocha | Exécutez des tests unitaires basés sur Mocha dans Node. |
test:unit-jest | Exécutez des tests unitaires basés sur Jest dans Node. |
e2e | Exécutez des tests de navigateur de bout en bout avec Cypress. |
lint | Exécuter le test ESLint |
test:artifact | Exécuter la liste des tests d'artefacts de bundle dans Jest |
test:artifact:umd:bundle | Exécutez un test unitaire qui confirme les exportations swagger-editor-bundle en tant que fonction |
test:artifact:es:bundle | Exécutez un test unitaire qui confirme les exportations swagger-editor-es-bundle en tant que fonction |
test:artifact:es:bundle:core | Exécutez un test unitaire qui confirme les exportations swagger-editor-es-bundle-core en tant que fonction |
$ npm i --legacy-peer-deps Si Node.js et npm sont installés, vous pouvez exécuter npm start pour démarrer un serveur statique.
Sinon, vous pouvez ouvrir index.html directement depuis votre système de fichiers dans votre navigateur.
Si vous souhaitez apporter des modifications au code de Swagger Editor, vous pouvez démarrer un serveur de développement à rechargement à chaud Webpack via npm run dev .
Swagger Editor fonctionne dans les dernières versions de Chrome, Safari, Firefox et Edge.
Pour vous aider dans la migration, voici les problèmes actuellement connus avec 3.X. Cette liste sera mise à jour régulièrement et n'inclura pas les fonctionnalités qui n'étaient pas implémentées dans les versions précédentes.
Il existe une image Docker publiée dans DockerHub.
Pour l'utiliser, exécutez ce qui suit :
docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor
Cela exécutera Swagger Editor (en mode détaché) sur le port 80 de votre ordinateur, vous pourrez donc l'ouvrir en accédant à http://localhost dans votre navigateur.
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor
json ou yaml à partir de votre hôte local : docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor
Remarque : Lorsque les variables d'environnement URL et SWAGGER_FILE sont définies, URL est prioritaire et SWAGGER_FILE est ignoré.
BASE_URL pour accéder à l'application - par exemple si vous souhaitez que l'application soit disponible sur http://localhost/swagger-editor/ : docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor
PORT pour accéder à l'application, la valeur par défaut est 8080 . docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor
GTM pour suivre l'utilisation de l'éditeur swagger. docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor
Vous pouvez également personnaliser les différents points de terminaison utilisés par l'éditeur Swagger avec les variables d'environnement suivantes. Par exemple, cela peut être utile si vous disposez de votre propre serveur générateur Swagger :
| Variable d'environnement | Valeur par défaut |
|---|---|
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 |
Si vous souhaitez exécuter Swagger Editor localement sans les fonctionnalités Codegen (Generate Server et Generate Client), vous pouvez définir les variables d'environnement ci-dessus sur null ( URL_SWAGGER2_CONVERTER=null ).
Pour créer et exécuter une image Docker avec le code extrait sur votre ordinateur, exécutez la commande suivante à partir du répertoire racine du projet :
# 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
Vous pouvez ensuite afficher l'application en accédant à http://localhost dans votre navigateur.
Importer votre document OpenAPI
Contribuer
Important
Par anciennes versions, nous faisons spécifiquement référence à React >=17 <18 .
Par défaut, le package swagger-editor@4 npm est livré avec la dernière version de React@18. Il est possible d'utiliser le package npm swagger-editor@4 avec une ancienne version de React.
Disons que mon application s'intègre au package swagger-editor@4 npm et utilise [email protected].
Afin d'informer le package npm swagger-editor@4 que j'en ai besoin pour utiliser ma version React, je dois utiliser les remplacements npm.
{
"dependencies" : {
"react" : " =17.0.2 " ,
"react-dom" : " =17.0.2 "
},
"overrides" : {
"swagger-editor" : {
"react" : " $react " ,
"react" : " $react-dom " ,
"react-redux" : " ^8 "
}
}
}Note
Les remplacements React et ReactDOM sont définis comme une référence à la dépendance. Puisque réagissez-redux@9 ne prend en charge que React >= 18 , nous devons utiliser réagir-redux@8 .
Afin d'informer le package swagger-editor@4 npm que j'en ai besoin pour utiliser ma version spécifique de React, je dois utiliser des résolutions de fil.
{
"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 "
}
}Note
La résolution React et ReactDOM ne peut pas être définie comme une référence à la dépendance. Malheureusement, Yarn ne prend pas en charge les alias comme $react ou $react-dom comme le fait npm . Vous devrez spécifier les versions exactes.
Veuillez divulguer tout problème ou vulnérabilité lié à la sécurité en envoyant un e-mail à [email protected], au lieu d'utiliser l'outil de suivi des problèmes public.
