swagger editor
v4.14.0 Released!
⏰️ ¿Busca la versión de próxima generación de Swagger Editor?
SwaggerEditor ahora se lanza bajo dos canales de lanzamiento principales:
Sólo SwaggerEditor@5 es compatible con OpenAPI 3.1.0. SwaggerEditor@4 no recibirá soporte para OpenAPI 3.1.0 y se considera heredado en este momento. El plan es migrar continuamente por completo a SwaggerEditor@5 y dejar de utilizar SwaggerEditor@4 en el futuro.
?️ ¿Buscas la versión anterior de Swagger Editor? Consulte las ramas 2.x o 3.x.
Swagger Editor le permite editar definiciones de API de OpenAPI (OpenAPI 2.0 y OpenAPI 3.0.3) en formato JSON o YAML dentro de su navegador y obtener una vista previa de la documentación en tiempo real. Luego se pueden generar y utilizar definiciones válidas de OpenAPI con las herramientas Swagger completas (generación de código, documentación, etc.).
Al ser una versión completamente nueva, escrita desde cero, existen algunos problemas conocidos y características no implementadas. Consulte la sección Problemas conocidos para obtener más detalles.
Este repositorio publica en dos módulos NPM diferentes:
Si está creando una aplicación de una sola página, se recomienda encarecidamente utilizar swagger-editor , ya que swagger-editor-dist es significativamente más grande.
Swagger Editor utiliza Bufanda para recopilar análisis de instalación anónimos. Estos análisis ayudan a los encargados de mantener esta biblioteca y SÓLO se ejecutan durante la instalación. Para optar por no participar, puede configurar el campo scarfSettings.enabled en false en package.json de su proyecto:
// package.json
{
// ...
"scarfSettings": {
"enabled": false
}
// ...
}
Alternativamente, puede configurar la variable de entorno SCARF_ANALYTICS en false como parte del entorno que instala sus paquetes npm, por ejemplo, SCARF_ANALYTICS=false npm install .
Cualquiera de los scripts siguientes se puede ejecutar escribiendo npm run <script name> en el directorio raíz del proyecto.
| Nombre del guión | Descripción |
|---|---|
dev | Genere un servidor de desarrollo de recarga en caliente en el puerto 3200. |
deps-check | Genere un informe de tamaño y licencia sobre las dependencias de Swagger Editors. |
lint | Informar errores y advertencias de estilo ESLint. |
lint-errors | Informar errores de estilo ESLint, sin advertencias. |
lint-fix | Intente corregir los errores de estilo automáticamente. |
watch | Reconstruya los archivos principales en /dist cuando cambie el código fuente. Útil para npm link . |
| Nombre del guión | Descripción |
|---|---|
build | Cree un nuevo conjunto de recursos JS y CSS y envíelos a /dist . |
build:bundle | Compile swagger-editor-bundle.js únicamente (commonJS). |
build:core | Compile swagger-editor.(js|css) únicamente (commonJS). |
build:standalone | Compile swagger-editor-standalone-preset.js únicamente (commonJS). |
build:stylesheets | Compile únicamente swagger-editor.css . |
build:es:bundle | Compile swagger-editor-es-bundle.js únicamente (es2015). |
build:es:bundle:core | Compile swagger-editor-es-bundle-core.js únicamente (es2015). |
| Nombre del guión | Descripción |
|---|---|
test | Ejecute pruebas unitarias en Node, ejecute pruebas de extremo a extremo de Cypress y ejecute ESLint en modo de solo errores. |
test:unit-mocha | Ejecute pruebas unitarias basadas en Mocha en Node. |
test:unit-jest | Ejecute pruebas unitarias basadas en Jest en Node. |
e2e | Ejecute pruebas de navegador de un extremo a otro con Cypress. |
lint | Ejecute la prueba ESLint |
test:artifact | Ejecute la lista de pruebas de artefactos del paquete en Jest |
test:artifact:umd:bundle | Ejecute una prueba unitaria que confirme las exportaciones swagger-editor-bundle como una función |
test:artifact:es:bundle | Ejecute una prueba unitaria que confirme las exportaciones swagger-editor-es-bundle como función |
test:artifact:es:bundle:core | Ejecute una prueba unitaria que confirme las exportaciones swagger-editor-es-bundle-core como función |
$ npm i --legacy-peer-deps Si tiene Node.js y npm instalados, puede ejecutar npm start para activar un servidor estático.
De lo contrario, puede abrir index.html directamente desde su sistema de archivos en su navegador.
Si desea realizar cambios de código en Swagger Editor, puede iniciar un servidor de desarrollo de recarga en caliente de Webpack a través de npm run dev .
Swagger Editor funciona en las últimas versiones de Chrome, Safari, Firefox y Edge.
Para ayudar con la migración, estos son los problemas conocidos actualmente con 3.X. Esta lista se actualizará periódicamente y no incluirá funciones que no se implementaron en versiones anteriores.
Hay una imagen de Docker publicada en DockerHub.
Para usar esto, ejecute lo siguiente:
docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor
Esto ejecutará Swagger Editor (en modo independiente) en el puerto 80 de su máquina, para que pueda abrirlo navegando a http://localhost en su navegador.
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor
json o yaml desde su host local: docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor
Nota: Cuando se configuran las variables de entorno URL y SWAGGER_FILE , URL tiene prioridad y SWAGGER_FILE se ignora.
BASE_URL para acceder a la aplicación; por ejemplo, si desea que la aplicación esté disponible en http://localhost/swagger-editor/ : docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor
PORT para acceder a la aplicación; el valor predeterminado es 8080 . docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor
GTM para realizar un seguimiento del uso del editor swagger. docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor
También puede personalizar los diferentes puntos finales utilizados por Swagger Editor con las siguientes variables de entorno. Por ejemplo, esto puede resultar útil si tiene su propio servidor generador Swagger:
| variable de entorno | Valor predeterminado |
|---|---|
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 desea ejecutar Swagger Editor localmente sin las funciones de Codegen (Generar servidor y Generar cliente), puede configurar las variables de entorno anteriores en null ( URL_SWAGGER2_CONVERTER=null ).
Para crear y ejecutar una imagen de Docker con el código extraído en su máquina, ejecute lo siguiente desde el directorio raíz del proyecto:
# 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
Luego puede ver la aplicación navegando a http://localhost en su navegador.
Importando su documento OpenAPI
Contribuyendo
Importante
Por versiones anteriores nos referimos específicamente a React >=17 <18 .
De forma predeterminada, el paquete swagger-editor@4 npm viene con la última versión de React@18. Es posible utilizar el paquete swagger-editor@4 npm con una versión anterior de React.
Digamos que mi aplicación se integra con el paquete swagger-editor@4 npm y usa [email protected].
Para informar al paquete swagger-editor@4 npm que necesito que use mi versión de React, necesito usar anulaciones de npm.
{
"dependencies" : {
"react" : " =17.0.2 " ,
"react-dom" : " =17.0.2 "
},
"overrides" : {
"swagger-editor" : {
"react" : " $react " ,
"react" : " $react-dom " ,
"react-redux" : " ^8 "
}
}
}Nota
La anulación de React y ReactDOM se define como una referencia a la dependencia. Dado que react-redux@9 solo admite React >= 18 , necesitamos usar react-redux@8 .
Para informar al paquete swagger-editor@4 npm que necesito que use mi versión específica de React, necesito usar resoluciones de hilo.
{
"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 "
}
}Nota
La resolución de React y ReactDOM no se puede definir como una referencia a la dependencia. Lamentablemente, Yarn no admite alias como $react o $react-dom como lo hace npm . Deberá especificar las versiones exactas.
Informe cualquier problema o vulnerabilidad relacionada con la seguridad enviando un correo electrónico a [email protected], en lugar de utilizar el rastreador de problemas público.
