swagger-editor

Swagger Editor

9,388

2,358

9,388

View on GitHub View on NPM

Top Related Projects

openapi-generator

25,204

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

spectral

2,887

A flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI (v3.1, v3.0, and v2.0), Arazzo v1.0, as well as AsyncAPI v2.x.

redoc

25,188

📘 OpenAPI/Swagger-generated API Reference Documentation

OpenAPI-Specification

30,558

The OpenAPI Specification Repository

openapi-to-postman

1,023

Plugin for converting OpenAPI 3.0 specs to the Postman Collection (v2) format

Quick Overview

Swagger Editor is a browser-based editor for designing, describing, and documenting RESTful APIs using the OpenAPI Specification (formerly known as Swagger). It provides a real-time preview of the API documentation and allows for easy editing of API definitions in YAML or JSON format.

Pros

Real-time visualization of API documentation
Built-in validation for OpenAPI Specification compliance
Supports both YAML and JSON formats
Integrates well with other Swagger tools and ecosystem

Cons

Limited offline functionality
Can be resource-intensive for large API definitions
Learning curve for users unfamiliar with OpenAPI Specification
Some advanced features may require additional setup or plugins

Getting Started

To use Swagger Editor, you can either:

Visit the online version at https://editor.swagger.io/
Run it locally using Docker:

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

Then open your browser and navigate to http://localhost:80.

Install it as an npm package:

npm install -g swagger-editor-dist
swagger-editor-dist serve

This will start a local server, and you can access the editor at http://localhost:3001.

Once you have the editor open, you can start defining your API by editing the YAML or JSON in the left panel. The right panel will update in real-time to show the rendered API documentation.

Competitor Comparisons

openapi-generator

25,204

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

Pros of openapi-generator

Supports a wide range of programming languages and frameworks for code generation
Offers more customization options for generated code
Provides a command-line interface for easy integration into build processes

Cons of openapi-generator

Steeper learning curve due to its extensive features and options
May require more setup and configuration compared to Swagger Editor

Code comparison

Swagger Editor (YAML editing):

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users

openapi-generator (CLI usage):

openapi-generator generate -i api.yaml -g java -o ./generated

Key differences

Swagger Editor is primarily a browser-based editor for OpenAPI specifications
openapi-generator focuses on generating client libraries, server stubs, and documentation
Swagger Editor provides real-time validation and visualization of API specifications
openapi-generator offers more flexibility in terms of output formats and customization

Use cases

Use Swagger Editor for creating and editing OpenAPI specifications visually
Choose openapi-generator for generating code across multiple languages and frameworks
Combine both tools in a workflow: design with Swagger Editor, then generate code with openapi-generator

spectral

2,887

A flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI (v3.1, v3.0, and v2.0), Arazzo v1.0, as well as AsyncAPI v2.x.

Pros of Spectral

More flexible and customizable linting rules
Can be used as a standalone CLI tool or integrated into CI/CD pipelines
Supports multiple API description formats (OpenAPI, AsyncAPI, JSON Schema)

Cons of Spectral

Lacks built-in editing capabilities
Requires more setup and configuration for advanced use cases
May have a steeper learning curve for beginners

Code Comparison

Spectral (custom rule):

module.exports = {
  rules: {
    'operation-description': {
      given: '$.paths.*[get,post,put,delete]',
      then: {
        field: 'description',
        function: 'truthy'
      }
    }
  }
};

Swagger Editor (built-in validation):

paths:
  /users:
    get:
      summary: Get users
      description: Retrieve a list of users
      responses:
        '200':
          description: Successful response

Spectral focuses on customizable linting and validation, while Swagger Editor provides a more integrated editing and preview experience for OpenAPI specifications. Spectral offers greater flexibility in rule creation and supports multiple API formats, making it suitable for complex validation scenarios. However, Swagger Editor excels in providing a user-friendly interface for editing and visualizing OpenAPI documents, which may be more accessible for users who prefer a GUI-based approach.

redoc

25,188

📘 OpenAPI/Swagger-generated API Reference Documentation

Pros of Redoc

Offers a more modern and visually appealing documentation interface
Provides better support for complex API structures and nested objects
Allows for easier customization of the documentation layout and styling

Cons of Redoc

Lacks built-in editing capabilities, focusing primarily on rendering
May require additional setup and configuration compared to Swagger Editor
Has a steeper learning curve for advanced customization

Code Comparison

Swagger Editor (YAML):

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users

Redoc (HTML):

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
  </head>
  <body>
    <redoc spec-url="path/to/openapi.yaml"></redoc>
  </body>
</html>

Swagger Editor is an all-in-one solution for editing and previewing OpenAPI specifications, while Redoc focuses on rendering beautiful and interactive API documentation. Swagger Editor provides a more integrated experience for API design and documentation, whereas Redoc excels in creating polished, user-friendly documentation for consumers of the API.

api-blueprint

8,671

API Blueprint

Pros of API Blueprint

Simpler, more human-readable syntax using Markdown
Better support for documentation-first API design
Easier to learn for non-technical stakeholders

Cons of API Blueprint

Less widespread adoption compared to Swagger/OpenAPI
Fewer tools and integrations available in the ecosystem
Limited support for complex API structures and advanced features

Code Comparison

API Blueprint:

# GET /users/{id}
+ Parameters
    + id: 1 (number, required) - User ID
+ Response 200 (application/json)
    + Attributes
        + name: John Doe (string)
        + email: john@example.com (string)

Swagger Editor (YAML):

/users/{id}:
  get:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string

Both Swagger Editor and API Blueprint are popular tools for API design and documentation. Swagger Editor, part of the OpenAPI ecosystem, offers a more comprehensive set of features and wider industry adoption. API Blueprint, on the other hand, provides a simpler, more readable syntax that can be easier for non-technical team members to understand and contribute to. The choice between the two often depends on the specific needs of the project and the team's preferences.

OpenAPI-Specification

30,558

The OpenAPI Specification Repository

Pros of OpenAPI-Specification

Serves as the official standard for API description
Provides a comprehensive, language-agnostic specification
Widely adopted and supported by various tools and platforms

Cons of OpenAPI-Specification

Lacks built-in editing capabilities
Requires additional tools for visualization and testing
May have a steeper learning curve for beginners

Code Comparison

OpenAPI-Specification (YAML):

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

Swagger-Editor (JavaScript):

SwaggerEditor.create(element, {
  swagger: '2.0',
  info: {
    title: 'Sample API',
    version: '1.0.0'
  }
});

Key Differences

OpenAPI-Specification focuses on defining the API structure
Swagger-Editor provides an interactive editing environment
OpenAPI-Specification is more flexible and extensible
Swagger-Editor offers real-time validation and documentation

Use Cases

OpenAPI-Specification: Standardizing API definitions across teams
Swagger-Editor: Rapid prototyping and visual API design

Community and Support

OpenAPI-Specification: Large community, extensive third-party tooling
Swagger-Editor: Well-maintained, part of the Swagger ecosystem

openapi-to-postman

1,023

Plugin for converting OpenAPI 3.0 specs to the Postman Collection (v2) format

Pros of openapi-to-postman

Specialized tool for converting OpenAPI specifications to Postman collections
Seamless integration with Postman ecosystem
Supports both OpenAPI 2.0 and 3.0 specifications

Cons of openapi-to-postman

Limited editing capabilities compared to Swagger Editor
Lacks real-time preview and validation features
Focused solely on conversion, not a full-fledged API design tool

Code Comparison

Swagger Editor (YAML editing):

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users

openapi-to-postman (JavaScript conversion):

const Converter = require('openapi-to-postmanv2');
Converter.convert({ type: 'string', data: openapiData },
  (err, conversionResult) => {
    // Handle conversion result
  }
);

While Swagger Editor provides a comprehensive environment for API design and documentation, openapi-to-postman focuses on bridging the gap between OpenAPI specifications and Postman collections. Swagger Editor offers real-time editing, validation, and preview capabilities, making it ideal for API designers. On the other hand, openapi-to-postman excels in converting existing OpenAPI specs to Postman format, enabling easier API testing and collaboration within the Postman ecosystem.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

SwaggerEditor

Anonymized analytics
Getting started
Development
Documentation
Docker
License
Software Bill Of Materials (SBOM)

Anonymized analytics

Swagger Editor uses Scarf to collect anonymized installation analytics. These analytics help support the maintainers of this library and ONLY run during installation. To opt out, you can set the scarfSettings.enabled field to false in your project's package.json:

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

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

Getting started

Prerequisites

These prerequisites are required both for installing SwaggerEditor as a npm package and local development setup.

node-gyp with Python 3.x
GLIBC >=2.29
emscripten or docker needs to be installed, we recommend going with a docker option

Installation

Assuming prerequisites are already installed, SwaggerEditor npm package is installable and works with Node.js >= 12.22.0. You can install SwaggerEditor via npm CLI by running the following command:

 $ npm install swagger-editor@alpha

NOTE: when using bundler to build your project which is using swagger-editor@5 npm package, you might run into following Node.js error: Reached heap limit Allocation failed - JavaScript heap out of memory. It's caused by significant amount of code that needs to be bundled. This error can be resolved by extending the Node.js max heap limit: export NODE_OPTIONS="--max_old_space_size=4096".

Usage

Use the package in your application:

index.js:

import React from 'react';
import ReactDOM from 'react-dom';
import SwaggerEditor from 'swagger-editor';
import 'swagger-editor/swagger-editor.css';

const url = "https://raw.githubusercontent.com/asyncapi/spec/v2.2.0/examples/streetlights-kafka.yml";

const MyApp = () => (
  <div>
    <h1>SwaggerEditor Integration</h1>
    <SwaggerEditor url={url} />
  </div>
);

self.MonacoEnvironment = {
  /**
   * We're building into the dist/ folder. When application starts on
   * URL=https://example.com then SwaggerEditor will look for
   * `apidom.worker.js` on https://example.com/dist/apidom.worker.js and
   * `editor.worker` on https://example.com/dist/editor.worker.js.
   */
  baseUrl: `${document.baseURI || location.href}dist/`,
}

ReactDOM.render(<MyApp />, document.getElementById('swagger-editor'));

webpack.config.js (webpack@5)

Install dependencies needed for webpack@5 to properly build SwaggerEditor.

 $ npm i stream-browserify --save-dev
 $ npm i https-browserify --save-dev
 $ npm i stream-http --save-dev
 $ npm i util --save-dev
 $ npm i buffer --save-dev
 $ npm i process --save-dev

const path = require('path');
const webpack = require('webpack');

module.exports = {
  mode: 'production',
  entry: {
    app: './index.js',
    'apidom.worker': 'swagger-editor/apidom.worker',
    'editor.worker': 'swagger-editor/editor.worker',
  },
  output: {
    globalObject: 'self',
    filename: '[name].js',
    path: path.resolve(__dirname, 'dist')
  },
  resolve: {
    fallback: {
      path: false,
      fs: false,
      http: require.resolve('stream-http'), // required for asyncapi parser
      https: require.resolve('https-browserify'), // required for asyncapi parser
      stream: require.resolve('stream-browserify'),
      util: require.resolve('util'),
      url: require.resolve('url'),
      buffer: require.resolve('buffer'),
      zlib: false,
    },
    alias: {
      // This alias make sure we don't pull two different versions of monaco-editor
      'monaco-editor': '/node_modules/monaco-editor',
      // This alias makes sure we're avoiding a runtime error related to this package
      '@stoplight/ordered-object-literal$': '/node_modules/@stoplight/ordered-object-literal/src/index.mjs',
      'react/jsx-runtime.js': 'react/jsx-runtime',
    },
  },
  plugins: [
    new webpack.ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
      process: ['process'],
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      },
      /**
       * The default way in which webpack loads wasm files wonât work in a worker,
       * so we will have to disable webpackâs default handling of wasm files and
       * then fetch the wasm file by using the file path that we get using file-loader.
       *
       * Resource: https://pspdfkit.com/blog/2020/webassembly-in-a-web-worker/
       *
       * Alternatively, WASM file can be bundled directly into JavaScript bundle as data URLs.
       * This configuration reduces the complexity of WASM file loading
       * but increases the overal bundle size:
       *
       * {
       *   test: /\.wasm$/,
       *   type: 'asset/inline',
       * }
       */
      {
        test: /\.wasm$/,
        loader: 'file-loader',
        type: 'javascript/auto', // this disables webpacks default handling of wasm
      },
    ]
  }
};

Alternative webpack.config.js (webpack@5)

We've already built Web Workers artifacts for you, and they're located inside our npm distribution package in dist/umd/ directory. To avoid the complexity of building the Web Worker artifacts, you can use those artifacts directly. This setup will work both for production and development (webpack-dev-server) and will significantly shorten your build process.

Install copy-webpack-plugin and other needed dependencies.

 $ npm i copy-webpack-plugin --save-dev
 $ npm i stream-browserify --save-dev
 $ npm i https-browserify --save-dev
 $ npm i stream-http --save-dev
 $ npm i util --save-dev
 $ npm i buffer --save-dev
 $ npm i process --save-dev

const path = require('path');
const webpack = require('webpack');
const CopyWebpackPlugin = require('copy-webpack-plugin');

module.exports = {
  mode: 'production',
  entry: {
    app: './index.js',
  },
  output: {
    globalObject: 'self',
    filename: 'static/js/[name].js',
    path: path.resolve(__dirname, 'dist')
  },
  resolve: {
    fallback: {
      path: false,
      fs: false,
      http: require.resolve('stream-http'), // required for asyncapi parser
      https: require.resolve('https-browserify'), // required for asyncapi parser
      stream: require.resolve('stream-browserify'),
      util: require.resolve('util'),
      url: require.resolve('url'),
      buffer: require.resolve('buffer'),
      zlib: false,
    },
    alias: {
      // This alias make sure we don't pull two different versions of monaco-editor
      'monaco-editor': '/node_modules/monaco-editor',
      // This alias makes sure we're avoiding a runtime error related to this package
      '@stoplight/ordered-object-literal$': '/node_modules/@stoplight/ordered-object-literal/src/index.mjs',
      'react/jsx-runtime.js': 'react/jsx-runtime',
    }
  },
  plugins: [
    new webpack.ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
      process: ['process'],
    }),
    new CopyWebpackPlugin({
      patterns: [
        {
          from: 'node_modules/swagger-editor/dist/umd/apidom.worker.js',
          to: 'static/js',
        },
        {
          from: 'node_modules/swagger-editor/dist/umd/editor.worker.js',
          to: 'static/js',
        }
      ]
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      },
      /**
       * The default way in which webpack loads wasm files wonât work in a worker,
       * so we will have to disable webpackâs default handling of wasm files and
       * then fetch the wasm file by using the file path that we get using file-loader.
       *
       * Resource: https://pspdfkit.com/blog/2020/webassembly-in-a-web-worker/
       *
       * Alternatively, WASM file can be bundled directly into JavaScript bundle as data URLs.
       * This configuration reduces the complexity of WASM file loading
       * but increases the overal bundle size:
       *
       * {
       *   test: /\.wasm$/,
       *   type: 'asset/inline',
       * }
       */
      {
        test: /\.wasm$/,
        loader: 'file-loader',
        type: 'javascript/auto', // this disables webpacks default handling of wasm
      },
    ]
  }
};

Development

Prerequisites

Assuming prerequisites are already installed, Node.js >=22.11.0 and npm >=10.9.0 are the minimum required versions that this repo runs on, but we recommend using the latest version of Node.js@20.

Setting up

If you use nvm, running following command inside this repository will automatically pick the right Node.js version for you:

 $ nvm use

Run the following commands to set up the repository for local development:

 $ git clone https://github.com/swagger-api/swagger-editor.git
 $ cd swagger-editor
 $ npm i
 $ npm start

npm scripts

Lint

 $ npm run lint

Runs unit and integration tests

 $ npm test

Runs E2E Cypress tests

Usage in development environment:

 $ npm run cy:dev

Usage in Continuous Integration (CI) environment:

 $ npm run cy:ci

Build

 $ npm run build

This script will build all the SwaggerEditor build artifacts - app, esm and umd.

Build artifacts

After building artifacts, every two new directories will be created: build/ and dist/.

build/

$ npm run build:app
$ npm run build:app:serve

Builds and serves standalone SwaggerEditor application and all it's assets on http://localhost:3050/.

dist/esm/

$ npm run build:bundle:esm

This bundle is suited for consumption by 3rd parties, which want to use SwaggerEditor as a library in their own applications and have their own build process.

dist/umd/

$ npm run build:bundle:umd

SwaggerEditor UMD bundle exports SwaggerEditor symbol on a global object. It's bundled with React defined as external. This allows the consumer to use his own version of React + ReactDOM and mount SwaggerEditor lazily.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta
    name="description"
    content="SwaggerEditor"
  />
  <title>SwaggerEditor</title>
  <link rel="stylesheet" href="./swagger-editor.css" />
</head>
<body>
  <div id="swagger-editor"></div>
  <script src="https://unpkg.com/react@18/umd/react.production.min.js" crossorigin></script>
  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js" crossorigin></script>
  <script src="./dist/umd/swagger-editor.js"></script>
  <script>
    const props = {
      url: 'https://raw.githubusercontent.com/asyncapi/spec/v2.2.0/examples/streetlights-kafka.yml',
    };
    const element = React.createElement(SwaggerEditor, props);
    const domContainer = document.querySelector('#swagger-editor');

    ReactDOM.render(element, domContainer);
  </script>
</body>
</html>

npm

SwaggerEditor is released as swagger-editor@5 npm package on npmjs.com. Package can also be produced manually by running the following commands (assuming you're already followed setting up steps):

 $ npm run build:bundle:esm
 $ npm run build:bundle:umd
 $ npm pack

Package mapping

SwaggerEditor maps its build artifacts in package.json file in the following way:

"unpkg": "./dist/umd/swagger-editor.js",
"module": "./dist/esm/swagger-editor.js",
"browser": "./dist/esm/swagger-editor.js",
"jsnext:main": "./dist/esm/swagger-editor.js",
"exports": {
  "./package.json": "./package.json",
  "./swagger-editor.css": "./dist/swagger-editor.css",
  ".": {
    "browser": "./dist/esm/swagger-editor.js"
  },
  "./plugins/*": {
    "browser": "./dist/esm/plugins/*/index.js",
    "node": "./dist/esm/plugins/*/index.js"
  },
  "./presets/*": {
    "browser": "./dist/esm/presets/*/index.js"
  },
  "./apidom.worker": {
    "browser": "./dist/esm/apidom.worker.js"
  },
  "./editor.worker": {
    "browser": "./dist/esm/editor.worker.js"
  }
}

To learn more about these fields please refer to webpack mainFields documentation or to Node.js Modules: Packages documentation.

Documentation

Using older version of React

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

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

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

npm

In order to inform swagger-editor@5 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@5 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.

Customization

Plug points

Environment Variables

It is possible to use an environment variable to specify a local JSON/YAML file or a remote URL for SwaggerEditor to load on startup. These environment variables will get baked in during build time into build artifacts.

Environment variables currently available:

Variable name	Description
`REACT_APP_DEFINITION_FILE`	Specifies a local file path, and the specified file must also be present in the `/public/static` directory
`REACT_APP_DEFINITION_URL`	Specifies a remote URL. This environment variable currently takes precedence over `REACT_APP_SWAGGER_FILE`
`REACT_APP_VERSION`	Specifies the version of this app. The version is read from `package.json` file.

Sample environment variable values can be found in .env file. For more information about using environment variables, please refer to adding Custom Environment Variables section of Create React App documentation.

Using preview plugins in SwaggerUI

SwaggerEditor comes with number of preview plugins that are responsible for rendering the definition that's being created in the editor. These plugins include:

EditorPreviewAsyncAPIPlugin - AsyncAPI specification rendering support
EditorPreviewAPIDesignSystemsPlugin - API Design Systems rendering support

With a bit of adapting, we can use these plugins with SwaggerUI to provide an ability to render AsyncAPI or API Design Systems definitions with SwaggerUI.

import SwaggerUI from 'swagger-ui';
import SwaggerUIStandalonePreset from 'swagger-ui/dist/swagger-ui-standalone-preset';
import 'swagger-editor/swagger-editor.css';
import EditorContentOriginPlugin from 'swagger-editor/plugins/editor-content-origin';
import EditorContentTypePlugin from 'swagger-editor/plugins/editor-content-type';
import EditorPreviewAsyncAPIPlugin from 'swagger-editor/plugins/editor-preview-asyncapi';
import EditorPreviewAPIDesignSystemsPlugin from 'swagger-editor/plugins/editor-preview-api-design-systems';
import SwaggerUIAdapterPlugin from 'swagger-editor/plugins/swagger-ui-adapter';

SwaggerUI({
  url: 'https://petstore.swagger.io/v2/swagger.json',
  dom_id: '#swagger-ui',
  presets: [SwaggerUI.presets.apis, SwaggerUIStandalonePreset],
  plugins: [
    EditorContentOriginPlugin,
    EditorContentTypePlugin,
    EditorPreviewAsyncAPIPlugin,
    EditorPreviewAPIDesignSystemsPlugin,
    SwaggerUIAdapterPlugin,
    SwaggerUI.plugins.DownloadUrl,
  ],
});

The key here is SwaggerUIAdapter plugin which adapts SwaggerEditor plugins to use directly with SwaggerUI.

Standalone mode

SwaggerUI standalone mode is supported as well. With standalone mode you'll get a TopBar with an input where URL of the definition can be provided and this definition is subsequently loaded by the SwaggerUI.

import SwaggerUI from 'swagger-ui';
import SwaggerUIStandalonePreset from 'swagger-ui/dist/swagger-ui-standalone-preset';
import 'swagger-ui/dist/swagger-ui.css';
import 'swagger-editor/swagger-editor.css';
import EditorContentOriginPlugin from 'swagger-editor/plugins/editor-content-origin';
import EditorContentTypePlugin from 'swagger-editor/plugins/editor-content-type';
import EditorPreviewAsyncAPIPlugin from 'swagger-editor/plugins/editor-preview-asyncapi';
import EditorPreviewAPIDesignSystemsPlugin from 'swagger-editor/plugins/editor-preview-api-design-systems';
import SwaggerUIAdapterPlugin from 'swagger-editor/plugins/swagger-ui-adapter';

SwaggerUI({
  url: 'https://petstore.swagger.io/v2/swagger.json',
  dom_id: '#swagger-ui',
  presets: [SwaggerUI.presets.apis, SwaggerUIStandalonePreset],
  plugins: [
    EditorContentOriginPlugin,
    EditorContentTypePlugin,
    EditorPreviewAsyncAPIPlugin,
    EditorPreviewAPIDesignSystemsPlugin,
    SwaggerUIAdapterPlugin,
    SwaggerUI.plugins.DownloadUrl,
  ],
  layout: 'StandaloneLayout',
});

Utilizing preview plugins via unpkg.com

It's possible to utilize preview plugins in a build-free way via unpkg.com to create a standalone multi-spec supporting version of SwaggerUI.

<!DOCTYPE html>
<html >
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta name="description" content="SwaggerUIMultifold" />
    <link rel="stylesheet" href="//unpkg.com/swagger-editor@5.0.0-alpha.102/dist/swagger-editor.css" />
  </head>
  <body style="margin:0; padding:0;">
    <section id="swagger-ui"></section>

    <script src="//unpkg.com/swagger-ui-dist@5.21.0/swagger-ui-bundle.js"></script>
    <script src="//unpkg.com/swagger-ui-dist@5.21.0/swagger-ui-standalone-preset.js"></script>
    <script>
      ui = SwaggerUIBundle({});
      // expose SwaggerUI React globally for SwaggerEditor to use
      window.React = ui.React;
    </script>
    <script src="//unpkg.com/swagger-editor@5.0.0-alpha.102/dist/umd/swagger-editor.js"></script>
    <script>
      SwaggerUIBundle({
        url: 'https://petstore3.swagger.io/api/v3/openapi.json',
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset,
        ],
        plugins: [
          SwaggerEditor.plugins.EditorContentOrigin,
          SwaggerEditor.plugins.EditorContentType,
          SwaggerEditor.plugins.EditorPreviewAsyncAPI,
          SwaggerEditor.plugins.EditorPreviewApiDesignSystems,
          SwaggerEditor.plugins.SwaggerUIAdapter,
          SwaggerUIBundle.plugins.DownloadUrl,
        ],
        layout: 'StandaloneLayout',
      });
    </script>
  </body>
</html>

Composing customized SwaggerEditor version

SwaggerEditor is just a number of SwaggerUI plugins used with swagger-ui-react. Customized SwaggerEditor can be created by composing individual plugins with either swagger-ui and swagger-ui-react.

Plugins

List of available plugins:

dialogs
dropdown-menu
dropzone
editor-content-fixtures
editor-content-from-file
editor-content-origin
editor-content-persistence
editor-content-read-only
editor-content-type
editor-monaco
editor-monaco-language-apidom
editor-monaco-yaml-paste
editor-preview
editor-preview-api-design-systems
editor-preview-asyncapi
editor-preview-swagger-ui
editor-safe-render
editor-textarea
layout
modals
props-change-watcher
splash-screen
swagger-ui-adapter
top-bar
versions

Individual plugins can be imported in the following way:

import EditorContentTypePlugin from 'swagger-editor/plugins/editor-content-type';
import EditorContentReadOnlyPlugin from 'swagger-editor/plugins/editor-content-read-only';

Presets

Along with plugins, presets are available as well. Preset is a collection of plugins that are design to work together to provide a compound feature.

List of available presets:

textarea
monaco

Individual presets can be imported in the following way:

import TextareaPreset from 'swagger-editor/presets/textarea';
import MonacoPreset from 'swagger-editor/presets/monaco';

NOTE: Please refer to the Plug points documentation of SwaggerUI to understand how presets are passed to SwaggerUI.

Composing with swagger-ui

import SwaggerUI from 'swagger-ui';
import 'swagger-ui/dist/swagger-ui.css';
import UtilPlugin from 'swagger-editor/plugins/util';
import VersionsPlugin from 'swaggereditor/plugins/versions';
import ModalsPlugin from 'swagger-editor/plugins/modals';
import DialogsPlugin from 'swagger-editor/plugins/dialogs';
import DropdownMenuPlugin from 'swagger-editor/plugins/dropdown-menu';
import DropzonePlugin from 'swagger-editor/plugins/dropzone';
import VersionsPlugin from 'swagger-editor/plugins/versions';
import EditorTextareaPlugin from 'swagger-editor/plugins/editor-textarea';
import EditorMonacoPlugin from 'swagger-editor/plugins/editor-monaco';
import EditorMonacoYamlPastePlugin from 'swagger-editor/plugins/editor-monaco-yaml-paste';
import EditorMonacoLanguageApiDOMPlugin from 'swagger-editor/plugins/editor-monaco-language-apidom';
import EditorContentReadOnlyPlugin from 'swagger-editor/plugins/editor-content-read-only';
import EditorContentOriginPlugin from 'swagger-editor/plugins/editor-content-origin';
import EditorContentTypePlugin from 'swagger-editor/plugins/editor-content-type';
import EditorContentPersistencePlugin from 'swagger-editor/plugins/editor-content-persistence';
import EditorContentFixturesPlugin from 'swagger-editor/plugins/editor-content-fixtures';
import EditorContentFromFilePlugin from 'swagger-editor/plugins/editor-content-from-file';
import EditorPreviewPlugin from 'swagger-editor/plugins/editor-preview';
import EditorPreviewSwaggerUIPlugin from 'swagger-editor/plugins/editor-preview-swagger-ui';
import EditorPreviewAsyncAPIPlugin from 'swagger-editor/plugins/editor-preview-asyncapi';
import EditorPreviewApiDesignSystemsPlugin from 'swagger-editor/plugins/editor-preview-api-design-systems';
import TopBarPlugin from 'swagger-editor/plugins/top-bar';
import SplashScreenPlugin from 'swagger-editor/plugins/splash-screen';
import LayoutPlugin from 'swagger-editor/plugins/layout';
import EditorSafeRenderPlugin from 'swagger-editor/plugins/editor-safe-render';

SwaggerUI({
  url: 'https://petstore.swagger.io/v2/swagger.json',
  dom_id: '#swagger-editor',
  plugins: [
    UtilPlugin,
    VersionsPlugin,
    ModalsPlugin,
    DialogsPlugin,
    DropdownMenuPlugin,
    DropzonePlugin,
    VersionsPlugin,
    EditorTextareaPlugin,
    EditorMonacoPlugin,
    EditorMonacoYamlPastePlugin,
    EditorMonacoLanguageApiDOMPlugin,
    EditorContentReadOnlyPlugin,
    EditorContentOriginPlugin,
    EditorContentTypePlugin,
    EditorContentPersistencePlugin,
    EditorContentFixturesPlugin,
    EditorContentFromFilePlugin,
    EditorPreviewPlugin,
    EditorPreviewSwaggerUIPlugin,
    EditorPreviewAsyncAPIPlugin,
    EditorPreviewApiDesignSystemsPlugin,
    TopBarPlugin,
    SplashScreenPlugin,
    LayoutPlugin,
    EditorSafeRenderPlugin,
  ],
  layout: 'StandaloneLayout',
});

Composing with swagger-ui-react

import React from 'react';
import ReactDOM from 'react-dom';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';
import UtilPlugin from 'swagger-editor/plugins/util';
import VersionsPlugin from 'swaggereditor/plugins/versions';
import ModalsPlugin from 'swagger-editor/plugins/modals';
import DialogsPlugin from 'swagger-editor/plugins/dialogs';
import DropdownMenuPlugin from 'swagger-editor/plugins/dropdown-menu';
import DropzonePlugin from 'swagger-editor/plugins/dropzone';
import VersionsPlugin from 'swagger-editor/plugins/versions';
import EditorTextareaPlugin from 'swagger-editor/plugins/editor-textarea';
import EditorMonacoPlugin from 'swagger-editor/plugins/editor-monaco';
import EditorMonacoYamlPastePlugin from 'swagger-editor/plugins/editor-monaco-yaml-paste';
import EditorMonacoLanguageApiDOMPlugin from 'swagger-editor/plugins/editor-monaco-language-apidom';
import EditorContentReadOnlyPlugin from 'swagger-editor/plugins/editor-content-read-only';
import EditorContentOriginPlugin from 'swagger-editor/plugins/editor-content-origin';
import EditorContentTypePlugin from 'swagger-editor/plugins/editor-content-type';
import EditorContentPersistencePlugin from 'swagger-editor/plugins/editor-content-persistence';
import EditorContentFixturesPlugin from 'swagger-editor/plugins/editor-content-fixtures';
import EditorContentFromFilePlugin from 'swagger-editor/plugins/editor-content-from-file';
import EditorPreviewPlugin from 'swagger-editor/plugins/editor-preview';
import EditorPreviewSwaggerUIPlugin from 'swagger-editor/plugins/editor-preview-swagger-ui';
import EditorPreviewAsyncAPIPlugin from 'swagger-editor/plugins/editor-preview-asyncapi';
import EditorPreviewApiDesignSystemsPlugin from 'swagger-editor/plugins/editor-preview-api-design-systems';
import TopBarPlugin from 'swagger-editor/plugins/top-bar';
import SplashScreenPlugin from 'swagger-editor/plugins/splash-screen';
import LayoutPlugin from 'swagger-editor/plugins/layout';
import EditorSafeRenderPlugin from 'swagger-editor/plugins/editor-safe-render';

const SwaggerEditor = () => {
  return (
    <SwaggerUI
      url={url}
      plugins={[
        UtilPlugin,
        VersionsPlugin,
        ModalsPlugin,
        DialogsPlugin,
        DropdownMenuPlugin,
        DropzonePlugin,
        VersionsPlugin,
        EditorTextareaPlugin,
        EditorMonacoPlugin,
        EditorMonacoYamlPastePlugin,
        EditorMonacoLanguageApiDOMPlugin,
        EditorContentReadOnlyPlugin,
        EditorContentOriginPlugin,
        EditorContentTypePlugin,
        EditorContentPersistencePlugin,
        EditorContentFixturesPlugin,
        EditorContentFromFilePlugin,
        EditorPreviewPlugin,
        EditorPreviewSwaggerUIPlugin,
        EditorPreviewAsyncAPIPlugin,
        EditorPreviewApiDesignSystemsPlugin,
        TopBarPlugin,
        SplashScreenPlugin,
        LayoutPlugin,
        EditorSafeRenderPlugin,
      ]}
      layout="StandaloneLayout"
    />
  );
};

ReactDOM.render(<SwaggerEditor />, document.getElementById('swagger-editor'));

Docker

Pre-built DockerHub image

SwaggerEditor is available as a pre-built docker image hosted on docker.swagger.io.

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

Building locally

Privileged image:

 $ npm run build:app
 $ docker build . -t swaggerapi/swagger-editor:latest
 $ docker run -d -p 8080:80 swaggerapi/swagger-editor:latest

Now open your browser at http://localhost:8080/.

Unprivileged image:

 $ npm run build:app
 $ docker build . -f Dockerfile.unprivileged -t swaggerapi/swagger-editor:latest-unprivileged
 $ docker run -d -p 8080:8080 swaggerapi/swagger-editor:latest-unprivileged

Now open your browser at http://localhost:8080/.

No custom environment variables are currently supported by SwaggerEditor.

License

SwaggerEditor is licensed under Apache 2.0 license. SwaggerEditor comes with an explicit NOTICE file containing additional legal notifications and information.

This project uses REUSE specification that defines a standardized method for declaring copyright and licensing for software projects.

Software Bill Of Materials (SBOM)

Software Bill Of materials is available in this repository dependency graph. Click on Export SBOM button to download the SBOM in SPDX format.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Getting Started

Competitor Comparisons

Pros of openapi-generator

Cons of openapi-generator

Code comparison

Key differences

Use cases

Pros of Spectral

Cons of Spectral

Code Comparison

Pros of Redoc

Cons of Redoc

Code Comparison

Pros of API Blueprint

Cons of API Blueprint

Code Comparison

Pros of OpenAPI-Specification

Cons of OpenAPI-Specification

Code Comparison

Key Differences

Use Cases

Community and Support

Pros of openapi-to-postman

Cons of openapi-to-postman

Code Comparison

Convert designs to code with AI

README

SwaggerEditor

Table of Contents

Anonymized analytics

Getting started

Prerequisites

Installation

Usage

Development

Prerequisites

Setting up

npm scripts

Build artifacts

Package mapping

Documentation

Using older version of React

npm

yarn

Customization

Environment Variables

Using preview plugins in SwaggerUI

Standalone mode

Utilizing preview plugins via unpkg.com

Composing customized SwaggerEditor version

Plugins

Presets

Composing with swagger-ui

Composing with swagger-ui-react

Docker

Pre-built DockerHub image

Building locally

License

Software Bill Of Materials (SBOM)

Top Related Projects

Convert designs to code with AI

NPM DownloadsLast 30 Days