Home

Awesome

<img src="https://raw.githubusercontent.com/swagger-api/swagger.io/wordpress/images/assets/SWE-logo-clr.png" height="80">

NPM version Build Status Code Climate Build Status

⏰️ 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:

If you're building a single-page application, using swagger-editor is strongly recommended, since swagger-editor-dist is significantly larger.

Helpful scripts

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

Developing

Script nameDescription
devSpawn a hot-reloading dev server on port 3200.
deps-checkGenerate a size and licensing report on Swagger Editors's dependencies.
lintReport ESLint style errors and warnings.
lint-errorsReport ESLint style errors, without warnings.
lint-fixAttempt to fix style errors automatically.
watchRebuild the core files in /dist when the source code changes. Useful for npm link.

Building

Script nameDescription
buildBuild a new set of JS and CSS assets, and output them to /dist.
build:bundleBuild swagger-editor-bundle.js only (commonJS).
build:coreBuild swagger-editor.(js|css) only (commonJS).
build:standaloneBuild swagger-editor-standalone-preset.js only (commonJS).
build:stylesheetsBuild swagger-editor.css only.
build:es:bundleBuild swagger-editor-es-bundle.js only (es2015).
build:es:bundle:coreBuild swagger-editor-es-bundle-core.js only (es2015).

Testing

Script nameDescription
testRun unit tests in Node, run Cypress end-to-end tests, and run ESLint in errors-only mode.
test:unit-mochaRun Mocha-based unit tests in Node.
test:unit-jestRun Jest-based unit tests in Node.
e2eRun end-to-end browser tests with Cypress.
lintRun ESLint test
test:artifactRun list of bundle artifact tests in Jest
test:artifact:umd:bundleRun unit test that confirms swagger-editor-bundle exports as a Function
test:artifact:es:bundleRun unit test that confirms swagger-editor-es-bundle exports as a Function
test:artifact:es:bundle:coreRun unit test that confirms swagger-editor-es-bundle-core exports as a Function

Running locally

Prerequisites

 $ npm i --legacy-peer-deps

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

Otherwise, you can open index.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 via npm run dev.

Browser support

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

Known Issues

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.

Docker

Running the image from DockerHub

There is a docker image published in DockerHub.

To use this, run the following:

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 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.

docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor
docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor

Note: When both URL and SWAGGER_FILE environment variables are set, URL has priority and SWAGGER_FILE is ignored.

docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor
docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor
docker run -d -p 80:8080 -e GTM=GTM-XXXXXX 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:

Environment variableDefault value
URL_SWAGGER2_GENERATORhttps://generator.swagger.io/api/swagger.json
URL_OAS3_GENERATORhttps://generator3.swagger.io/openapi.json
URL_SWAGGER2_CONVERTERhttps://converter.swagger.io/api/convert

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

Using older version of React

[!IMPORTANT] By older versions we specifically refer to React >=17 <18.

By default swagger-editor@4 npm package comes with latest version of React@18. It's possible to use swagger-editor@4 npm package with older version of React.

Let's say my application integrates with swagger-editor@4 npm package and uses React@17.0.2.

npm

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

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

[!NOTE] The React and ReactDOM override are defined as a reference to the dependency. Since react-redux@9 only supports React >= 18, we need to use react-redux@8.

yarn

In order to inform swagger-editor@4 npm package that I require it to use my specific React version, I need to use yarn 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"
  }
}

[!NOTE] The React and ReactDOM resolution cannot be defined as a reference to the dependency. Unfortunately yarn does not support aliasing like $react or $react-dom as npm does. You'll need to specify the exact versions.

Security contact

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