swagger editor
v4.14.0 Released!
⏰️ Suchen Sie nach der nächsten Generation des Swagger Editors?
SwaggerEditor wird jetzt unter zwei großen Veröffentlichungskanälen veröffentlicht:
Nur SwaggerEditor@5 unterstützt OpenAPI 3.1.0. SwaggerEditor@4 erhält keine OpenAPI 3.1.0-Unterstützung und gilt zu diesem Zeitpunkt als veraltet. Der Plan besteht darin, kontinuierlich vollständig auf SwaggerEditor@5 zu migrieren und den SwaggerEditor@4 in Zukunft abzuschaffen.
?️ Suchen Sie nach der älteren Version des Swagger Editors? Weitere Informationen finden Sie in den Zweigen 2.x oder 3.x.
Mit dem Swagger Editor können Sie OpenAPI-API-Definitionen (OpenAPI 2.0 und OpenAPI 3.0.3) im JSON- oder YAML-Format in Ihrem Browser bearbeiten und Dokumentationen in Echtzeit in der Vorschau anzeigen. Anschließend können gültige OpenAPI-Definitionen generiert und mit den vollständigen Swagger-Tools (Codegenerierung, Dokumentation usw.) verwendet werden.
Da es sich um eine brandneue Version handelt, die von Grund auf neu geschrieben wurde, gibt es einige bekannte Probleme und nicht implementierte Funktionen. Weitere Informationen finden Sie im Abschnitt „Bekannte Probleme“.
Dieses Repository veröffentlicht in zwei verschiedenen NPM-Modulen:
Wenn Sie eine einseitige Anwendung erstellen, wird die Verwendung swagger-editor dringend empfohlen, da swagger-editor-dist deutlich größer ist.
Swagger Editor verwendet Scarf, um anonymisierte Installationsanalysen zu sammeln. Diese Analysen unterstützen die Betreuer dieser Bibliothek und werden NUR während der Installation ausgeführt. Um sich abzumelden, können Sie das Feld scarfSettings.enabled in package.json Ihres Projekts auf false setzen:
// package.json
{
// ...
"scarfSettings": {
"enabled": false
}
// ...
}
Alternativ können Sie die Umgebungsvariable SCARF_ANALYTICS als Teil der Umgebung, die Ihre npm-Pakete installiert, auf false setzen, z. B. SCARF_ANALYTICS=false npm install .
Jedes der folgenden Skripte kann durch Eingabe von npm run <script name> im Stammverzeichnis des Projekts ausgeführt werden.
| Skriptname | Beschreibung |
|---|---|
dev | Erstellen Sie einen Hot-Reloading-Entwicklungsserver auf Port 3200. |
deps-check | Erstellen Sie einen Größen- und Lizenzbericht über die Abhängigkeiten von Swagger Editors. |
lint | Melden Sie Fehler und Warnungen im ESLint-Stil. |
lint-errors | Melden Sie Fehler im ESLint-Stil ohne Warnungen. |
lint-fix | Versuchen Sie, Stilfehler automatisch zu beheben. |
watch | Erstellen Sie die Kerndateien in /dist neu, wenn sich der Quellcode ändert. Nützlich für npm link . |
| Skriptname | Beschreibung |
|---|---|
build | Erstellen Sie einen neuen Satz von JS- und CSS-Assets und geben Sie sie in /dist aus. |
build:bundle | Erstellen Sie nur swagger-editor-bundle.js (commonJS). |
build:core | Erstellen Sie nur swagger-editor.(js|css) (commonJS). |
build:standalone | Erstellen Sie nur swagger-editor-standalone-preset.js (commonJS). |
build:stylesheets | Erstellen Sie nur swagger-editor.css . |
build:es:bundle | Erstellen Sie nur swagger-editor-es-bundle.js (es2015). |
build:es:bundle:core | Erstellen Sie nur swagger-editor-es-bundle-core.js (es2015). |
| Skriptname | Beschreibung |
|---|---|
test | Führen Sie Unit-Tests in Node aus, führen Sie Cypress-End-to-End-Tests durch und führen Sie ESLint im Nur-Fehler-Modus aus. |
test:unit-mocha | Führen Sie Mocha-basierte Unit-Tests in Node aus. |
test:unit-jest | Führen Sie Jest-basierte Komponententests in Node aus. |
e2e | Führen Sie End-to-End-Browsertests mit Cypress durch. |
lint | Führen Sie den ESLint-Test aus |
test:artifact | Führen Sie eine Liste von Bundle-Artefakttests in Jest aus |
test:artifact:umd:bundle | Führen Sie einen Unit-Test durch, der swagger-editor-bundle Exporte als Funktion bestätigt |
test:artifact:es:bundle | Führen Sie einen Unit-Test durch, der die Exporte von swagger-editor-es-bundle als Funktion bestätigt |
test:artifact:es:bundle:core | Führen Sie einen Unit-Test durch, der die Exporte swagger-editor-es-bundle-core als Funktion bestätigt |
$ npm i --legacy-peer-deps Wenn Sie Node.js und npm installiert haben, können Sie npm start ausführen, um einen statischen Server hochzufahren.
Andernfalls können Sie index.html direkt aus Ihrem Dateisystem in Ihrem Browser öffnen.
Wenn Sie Codeänderungen am Swagger Editor vornehmen möchten, können Sie über npm run dev einen Webpack-Entwicklungsserver zum Hot-Reloading starten.
Swagger Editor funktioniert in den neuesten Versionen von Chrome, Safari, Firefox und Edge.
Um die Migration zu erleichtern, finden Sie hier die derzeit bekannten Probleme mit 3.X. Diese Liste wird regelmäßig aktualisiert und enthält keine Funktionen, die in früheren Versionen nicht implementiert waren.
Es gibt ein Docker-Image, das in DockerHub veröffentlicht wurde.
Um dies zu verwenden, führen Sie Folgendes aus:
docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor
Dadurch wird der Swagger Editor (im getrennten Modus) auf Port 80 auf Ihrem Computer ausgeführt, sodass Sie ihn öffnen können, indem Sie in Ihrem Browser zu http://localhost navigieren.
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor
json oder yaml Definitionsdatei von Ihrem lokalen Host bereitstellen: docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor
Hinweis: Wenn sowohl die Umgebungsvariablen URL als auch SWAGGER_FILE festgelegt sind, hat URL Priorität und SWAGGER_FILE wird ignoriert.
BASE_URL eine andere Basis-URL für den Zugriff auf die Anwendung angeben – zum Beispiel, wenn Sie möchten, dass die Anwendung unter http://localhost/swagger-editor/ verfügbar ist: docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor
PORT einen anderen Port für den Zugriff auf die Anwendung angeben, der Standardwert ist 8080 . docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor
GTM Variable angeben, um die Nutzung des Swagger-Editors zu verfolgen. docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor
Sie können die verschiedenen vom Swagger-Editor verwendeten Endpunkte auch mit den folgenden Umgebungsvariablen anpassen. Dies kann beispielsweise nützlich sein, wenn Sie über einen eigenen Swagger-Generatorserver verfügen:
| Umgebungsvariable | Standardwert |
|---|---|
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 |
Wenn Sie den Swagger-Editor lokal ohne die Codegen-Funktionen (Generate Server und Generate Client) ausführen möchten, können Sie die oben genannten Umgebungsvariablen auf null setzen ( URL_SWAGGER2_CONVERTER=null ).
Um ein Docker-Image mit dem auf Ihrem Computer ausgecheckten Code zu erstellen und auszuführen, führen Sie Folgendes im Stammverzeichnis des Projekts aus:
# 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
Sie können die App dann anzeigen, indem Sie in Ihrem Browser zu http://localhost navigieren.
Importieren Ihres OpenAPI-Dokuments
Mitwirken
Wichtig
Bei älteren Versionen beziehen wir uns ausdrücklich auf React >=17 <18 .
Standardmäßig wird das swagger-editor@4 npm-Paket mit der neuesten Version von React@18 geliefert. Es ist möglich , das swagger-editor@4 npm-Paket mit einer älteren Version von React zu verwenden.
Nehmen wir an, meine Anwendung lässt sich in das NPM-Paket swagger-editor@4 integrieren und verwendet [email protected].
Um swagger-editor@4 npm-Paket darüber zu informieren, dass ich es für die Verwendung meiner React-Version benötige, muss ich npm-Überschreibungen verwenden.
{
"dependencies" : {
"react" : " =17.0.2 " ,
"react-dom" : " =17.0.2 "
},
"overrides" : {
"swagger-editor" : {
"react" : " $react " ,
"react" : " $react-dom " ,
"react-redux" : " ^8 "
}
}
}Notiz
Die React- und ReactDOM-Overrides werden als Verweis auf die Abhängigkeit definiert. Da „react-redux@9“ nur React >= 18 unterstützt, müssen wir „react-redux@8“ verwenden.
Um swagger-editor@4 npm-Paket darüber zu informieren, dass ich es für die Verwendung meiner spezifischen React-Version benötige, muss ich Garnauflösungen verwenden.
{
"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 "
}
}Notiz
Die React- und ReactDOM-Auflösung kann nicht als Verweis auf die Abhängigkeit definiert werden. Leider unterstützt Garn kein Aliasing wie $react oder $react-dom wie npm . Sie müssen die genauen Versionen angeben.
Bitte melden Sie alle sicherheitsrelevanten Probleme oder Schwachstellen per E-Mail an [email protected], anstatt den öffentlichen Issue-Tracker zu verwenden.
