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.
These prerequisites are required both for installing SwaggerEditor as a npm package and local development setup.
>=2.29Assuming 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**:
```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 = () => (
<h1>SwaggerEditor Integration</h1>
<SwaggerEditor url={url} />
);
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,
* `editor.worker` on https://example.com/dist/editor.worker.js and
* `asyncapi-parser.worker.js` on https://example.com/dist/asyncapi-parser.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',
'asyncapi-parser.worker': 'swagger-editor/asyncapi-parser.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',
},
{
from: 'node_modules/swagger-editor/dist/umd/asyncapi-parser.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
},
]
}
};
Assuming prerequisites are already installed, Node.js >=24.14.0 and npm >=11.9.0
are the minimum required versions that this repo runs on, but we recommend using the latest version of Node.js@24.
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
Lint
$ npm run lint
Runs unit tests
$ npm test # watch mode
$ npm run test:run # single run (CI)
$ npm run test:coverage # with coverage report
Runs E2E tests
Usage in development environment:
$ npx playwright test --headed # Run with browser visible
$ npx playwright test --ui # Run with Playwright UI
$ npx playwright test --debug # Run in debug mode
Usage in Continuous Integration (CI) environment:
$ npx playwright test # Run all tests headless
View test report:
$ npx playwright show-report test/playwright/report
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/**
```sh
$ 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="https://github.com/swagger-api/swagger-editor/raw/v5.7.0/swagger-editor.css" />
</head>
<body>
<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="https://github.com/swagger-api/swagger-editor/raw/v5.7.0/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
SwaggerEditor maps its build artifacts in package.json file in the following way:
```json "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" }, "./asyncapi-parser.worker":
$ claude mcp add swagger-editor \
-- python -m otcore.mcp_server <graph>