swaggerapi/swagger-editor repository overview

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

SwaggerEditor is now released under two major release channels:

1. SwaggerEditor@4⁠ - released from master⁠ branch and deployed at https://editor.swagger.io/⁠
2. SwaggerEditor@5⁠ - released from next⁠ branch and deployed at https://editor-next.swagger.io/⁠

Only SwaggerEditor@5 supports OpenAPI 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 the 2.x⁠ or 3.x⁠ branches.

Swagger Editor lets you edit OpenAPI API definitions (OpenAPI 2.0⁠ and OpenAPI 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 the Known 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, using swagger-editor is strongly recommended, since swagger-editor-dist is significantly larger.

⁠Browser support

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

⁠Docker

⁠Running the image from DockerHub

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

To use this, run the following:

docker pull docker.swagger.io/swaggerapi/swagger-editor
docker 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 to http://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 own json or yaml 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 both URL and SWAGGER_FILE environment variables are set, URL has priority and SWAGGER_FILE is ignored.

• You can specify a different base url via BASE_URL variable for accessing the application - for example if you want the application to be available at http://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 via PORT variable for accessing the application, default is 8080.

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

• You can specify Google Tag Manager ID via GTM 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 to null (URL_SWAGGER2_CONVERTER=null).

⁠Building and running an image locally

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 app
npm run build

# Build an image
docker build -t swagger-editor .

# Run the container
docker run -d -p 80:8080 swagger-editor

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

⁠Documentation

• Importing your OpenAPI document⁠

• Contributing⁠

⁠Security contact

Please disclose any security-related issues or vulnerabilities by emailing [email protected]⁠, instead of using the public issue tracker.