Repository files navigation

⏰️ Looking for the next generation version of Swagger Editor?

SwaggerEditor is now released under two major release channels:

1. SwaggerEditor@4 - released frommaster branch and deployed athttps://editor.swagger.io/
2. SwaggerEditor@5 - released fromnext branch and deployed athttps://editor-next.swagger.io/

OnlySwaggerEditor@5 supportsOpenAPI 3.1.0.SwaggerEditor@4 will not receive OpenAPI 3.1.0 support and is considered legacy at this point.The plan is to continually migrate fully to SwaggerEditor@5 and deprecate the SwaggerEditor@4 in the future.

🕰️ Looking for the older version of Swagger Editor? Refer to the2.x or3.x branches.

Swagger Editor lets you editOpenAPI API definitions (OpenAPI 2.0 andOpenAPI 3.0.3)in JSON or YAML format inside your browser and to preview documentations in real time.Valid OpenAPI definitions can then be generated and used with the full Swagger tooling (code generation, documentation, etc).

As a brand-new version, written from the ground up, there are some known issues and unimplemented features. Check out theKnown Issues section for more details.

This repository publishes to two different NPM modules:

• swagger-editor is a traditional npm module intended for use in single-page applications that are capable of resolving dependencies (via Webpack, Browserify, etc).
• swagger-editor-dist is a dependency-free module that includes everything you need to serve Swagger Editor in a server-side project, or a web project that can't resolve npm module dependencies.

If you're building a single-page application, usingswagger-editor is strongly recommended, sinceswagger-editor-dist is significantly larger.

Swagger Editor usesScarf to collectanonymized installation analytics. These analytics help support the maintainers of this library and ONLY run during installation. Toopt out, you can set thescarfSettings.enabled field tofalse in your project'spackage.json:

// package.json{  // ...  "scarfSettings": {    "enabled": false  }  // ...}

Alternatively, you can set the environment variableSCARF_ANALYTICS tofalse as part of the environment that installs your npm packages, e.g.,SCARF_ANALYTICS=false npm install.

Any of the scripts below can be run by typingnpm run <script name> in the project's root directory.

• git, any version
• Node.js >=20.3.0 andnpm >=9.6.7 are the minimum required versions that this repo runs on, but we always recommend using the latest version of Node.js.

 $ npm i --legacy-peer-deps

If you have Node.js and npm installed, you can runnpm start to spin up a static server.

Otherwise, you can openindex.html directly from your filesystem in your browser.

If you'd like to make code changes to Swagger Editor, you can start up a Webpack hot-reloading dev server vianpm run dev.

Swagger Editor works in the latest versions of Chrome, Safari, Firefox, and Edge.

To help with the migration, here are the currently known issues with 3.X. This list will update regularly, and will not include features that were not implemented in previous versions.

• Everything listed inSwagger UI's Known Issues.
• The integration with the codegen is still missing.

There is a docker image published indocker.swagger.io registry.

To use this, run the following:

docker pull docker.swagger.io/swaggerapi/swagger-editordocker run -d -p 80:8080 docker.swagger.io/swaggerapi/swagger-editor

This will run Swagger Editor (in detached mode) on port 80 on your machine, so you can open it by navigating tohttp://localhost in your browser.

• You can provide a URL pointing to an API definition (may not be available if some security policies such as CSP or CORS are enforced):

docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" docker.swagger.io/swaggerapi/swagger-editor

• You can provide your ownjson oryaml definition file from your local host:

docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json docker.swagger.io/swaggerapi/swagger-editor

Note: When bothURL andSWAGGER_FILE environment variables are set,URL has priority andSWAGGER_FILE is ignored.

• You can specify a different base url viaBASE_URL variable for accessing the application - for example if you want the application to be available athttp://localhost/swagger-editor/:

docker run -d -p 80:8080 -e BASE_URL=/swagger-editor docker.swagger.io/swaggerapi/swagger-editor

• You can specify a different port viaPORT variable for accessing the application, default is8080.

docker run -d -p 80:80 -e PORT=80 docker.swagger.io/swaggerapi/swagger-editor

• You can specify Google Tag Manager ID viaGTM variable for tracking the usage of the swagger-editor.

docker run -d -p 80:8080 -e GTM=GTM-XXXXXX docker.swagger.io/swaggerapi/swagger-editor

You can also customize the different endpoints used by the Swagger Editor with the following environment variables. For instance, this can be useful if you have your own Swagger generator server:

If you want to run the Swagger Editor locally without the Codegen features (Generate Server and Generate Client) you can set the above environment variables tonull (URL_SWAGGER2_CONVERTER=null).

To build and run a docker image with the code checked out on your machine, run the following from the root directory of the project:

# Install npm packages (if needed)npm install# Build the appnpm run build# Build an imagedocker build -t swagger-editor .# Run the containerdocker run -d -p 80:8080 swagger-editor

You can then view the app by navigating tohttp://localhost in your browser.

• Importing your OpenAPI document

• Contributing

By defaultswagger-editor@4 npm package comes with latest version ofReact@18.It's possible to useswagger-editor@4 npm package with older version of React.

Let's say my application integrates withswagger-editor@4 npm package and usesReact@17.0.2.

In order to informswagger-editor@4 npm package that I require it to use my React version, I need to usenpm overrides.

{"dependencies": {"react":"=17.0.2","react-dom":"=17.0.2"  },"overrides": {"swagger-editor": {"react":"$react","react":"$react-dom","react-redux":"^8"    }  }}

In order to informswagger-editor@4 npm package that I require it to use my specific React version, I need to useyarn resolutions.

{"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"  }}

Please disclose any security-related issues or vulnerabilities by emailingsecurity@swagger.io, instead of using the public issue tracker.