Required dependencies

npm install user@example.com swagger-ui-react react react-dom
npm install @mui/material @emotion/react @emotion/styled
npm install @primer/octicons-react
npm install @swagger-api/apidom-core @swagger-api/apidom-json-pointer @swagger-api/apidom-ls
npm install @swagger-api/apidom-ns-openapi-2 @swagger-api/apidom-ns-openapi-3-0 \
            @swagger-api/apidom-ns-openapi-3-1 @swagger-api/apidom-ns-openapi-3-2
npm install @swagger-api/apidom-ns-api-design-systems
npm install @swagger-api/apidom-parser-adapter-json \
            @swagger-api/apidom-parser-adapter-openapi-json-2 \
            @swagger-api/apidom-parser-adapter-openapi-json-3-0 \
            @swagger-api/apidom-parser-adapter-api-design-systems-json \
            @swagger-api/apidom-parser-adapter-api-design-systems-yaml \
            @swagger-api/apidom-parser-adapter-asyncapi-json-2 \
            @swagger-api/apidom-parser-adapter-asyncapi-yaml-2
npm install @asyncapi/parser @asyncapi/react-component \
            @asyncapi/avro-schema-parser @asyncapi/openapi-schema-parser \
            @asyncapi/protobuf-schema-parser
npm install @codingame/monaco-vscode-api

Native / build requirements:

• node-gyp with Python 3.x (required by native Monaco worker build)
• GLIBC >= 2.29 on Linux
• emscripten or Docker for WASM compilation of ApiDOM workers
• Extend Node.js heap before bundling: export NODE_OPTIONS="--max_old_space_size=4096"

Project setup

1. Copy the source/ directory into your project, e.g. src/swagger-editor-source/.
2. In webpack.config.js (webpack 5) add the polyfill aliases and worker output:

// webpack.config.js
const webpack = require('webpack');
module.exports = {
  resolve: {
    alias: {
      stream: 'stream-browserify',
      buffer: 'buffer',
      process: 'process/browser',
    },
    fallback: { https: 'https-browserify', http: 'stream-http', util: 'util' },
  },
  entry: {
    app: './src/index.tsx',
    'apidom.worker': './node_modules/swagger-editor/src/apidom.worker.js',
    'editor.worker': './node_modules/monaco-editor/esm/vs/editor/editor.worker.js',
  },
  plugins: [new webpack.ProvidePlugin({ process: 'process/browser', Buffer: ['buffer', 'Buffer'] })],
};

3. Add tsconfig.json path alias if importing source directly:

{
  "compilerOptions": {
    "paths": { "@editor/*": ["src/swagger-editor-source/*"] }
  }
}

4. Set MonacoEnvironment before mounting the component (see examples below).
5. Import the SwaggerUI CSS once at your app entry: import 'swagger-ui-react/swagger-ui.css';

Public API

DialogsPlugin

const DialogsPlugin: () => {
  components: {
    AlertDialog: React.ComponentType;
    ConfirmDialog: React.ComponentType;
  };
};
export default DialogsPlugin;

Register with the SwaggerEditor plugin system to gain AlertDialog and ConfirmDialog components on the system bus. Use when you need modal dialogs that block the entire editor UI until the user confirms or dismisses.

DropzonePlugin

const DropzonePlugin: ({ getSystem }: { getSystem: () => System }) => {
  rootInjects: { useDropzone: ReturnType<typeof makeUseDropzone> };
  components: { Dropzone: React.ComponentType };
  statePlugins: {
    editorDropzone: {
      actions: { dropFile; dropFileStarted; dropFileSuccess; dropFileFailure };
      wrapActions: { dropFileSuccess: typeof dropFileSuccessWrap };
    };
  };
};
export default DropzonePlugin;

Provides a drag-and-drop surface plus Redux-style actions (dropFile, dropFileStarted, dropFileSuccess, dropFileFailure) dispatched through the plugin bus. Use when you want to let users load local API definition files by dropping them onto the editor surface.

EditorContentFixturesPlugin

const EditorContentFixturesPlugin: () => {
  statePlugins: {
    editorContentFixtures: {
      selectors: {
        selectOpenAPI320PetstoreYAML: (state: unknown) => string;
        selectOpenAPI310PetstoreYAML: (state: unknown) => string;
        selectOpenAPI304PetstoreYAML: (state: unknown) => string;
        selectOpenAPI20PetstoreYAML: (state: unknown) => string;
        selectAsyncAPI260PetstoreYAML: (state: unknown) => string;
        selectAsyncAPI300PetstoreYAML: (state: unknown) => string;
        selectAsyncAPI260StreetlightsYAML: (state: unknown) => string;
        selectAsyncAPI300StreetlightsYAML: (state: unknown) => string;
        selectJSONSchema202012YAML: (state: unknown) => string;
        selectAPIDesignSystemsYAML: (state: unknown) => string;
      };
    };
  };
};
export default EditorContentFixturesPlugin;

Exposes selectors that return bundled YAML fixture strings for every supported spec type. Use for "Load Example" menu items or automated testing without network requests.

DropdownMenuPlugin

const DropdownMenuPlugin: () => {
  components: {
    DropdownMenu: React.ComponentType;
    DropdownMenuNested: React.ComponentType;
    DropdownMenuItem: React.ComponentType;
    DropdownMenuItemDivider: React.ComponentType;
  };
};
export default DropdownMenuPlugin;

Registers accessible, nestable dropdown menu primitives into the system component registry. Use when building custom top-bar menus that need keyboard navigation and screen-reader support.

Working examples

Scenario - Minimal editor embed

Mount the editor with a remote URL, configure Monaco worker paths, and let the built-in plugins handle everything else.

// src/EditorPage.tsx
import React from 'react';
import SwaggerEditor from './swagger-editor-source/App';
import 'swagger-ui-react/swagger-ui.css';

// Tell Monaco where to find the compiled workers.
(self as any).MonacoEnvironment = {
  baseUrl: `${document.baseURI || location.href}dist/`,
};

const PETSTORE_URL =
  'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml';

export const EditorPage: React.FC = () => (
  <div style={{ height: '100vh' }}>
    <SwaggerEditor url={PETSTORE_URL} />
  </div>
);

Scenario - Compose custom plugins with fixture selectors

Register EditorContentFixturesPlugin alongside core plugins and wire a "Load Example" button that dispatches content from a built-in YAML fixture.

// src/CustomEditorWithFixtures.tsx
import React from 'react';
import SwaggerEditor from './swagger-editor-source/App';
import EditorContentFixturesPlugin from './swagger-editor-source/plugins/editor-content-fixtures/index.js';
import 'swagger-ui-react/swagger-ui.css';

(self as any).MonacoEnvironment = { baseUrl: `${document.baseURI}dist/` };

// EditorContentFixturesPlugin is passed via the `plugins` prop exposed by App.tsx
// alongside the default preset; consult presets/ for the default plugin list.
export const CustomEditor: React.FC = () => (
  <SwaggerEditor
    plugins={[EditorContentFixturesPlugin]}
    url=""
  />
);

Scenario - Standalone dropzone file loader

Use DropzonePlugin and DropdownMenuPlugin in a custom shell that lets users drag a local YAML file and see it rendered in the preview panel.

// src/DropzoneEditor.tsx
import React from 'react';
import SwaggerEditor from './swagger-editor-source/App';
import DropzonePlugin from './swagger-editor-source/plugins/dropzone/index.js';
import DropdownMenuPlugin from './swagger-editor-source/plugins/dropdown-menu/index.js';
import DialogsPlugin from './swagger-editor-source/plugins/dialogs/index.js';
import 'swagger-ui-react/swagger-ui.css';

(self as any).MonacoEnvironment = { baseUrl: `${document.baseURI}dist/` };

export const DropzoneEditor: React.FC = () => (
  <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
    <SwaggerEditor
      plugins={[DropzonePlugin, DropdownMenuPlugin, DialogsPlugin]}
    />
  </div>
);

File walkthrough

• App.tsx - Exports the default SwaggerEditor React component; accepts url, plugins, and queryConfigEnabled props and assembles the full plugin system.
• index.tsx - CRA entry point that mounts App into #swagger-editor; not a library export, used only for the standalone dev/production build.
• reportWebVitals.ts - Optional Core Web Vitals reporter; pass a callback or omit entirely in library usage.
• plugins/dialogs/ - Registers AlertDialog and ConfirmDialog into the system component map; dialogs block all editor interaction while open.
• plugins/dropdown-menu/ - Provides four composable menu primitives (DropdownMenu, DropdownMenuNested, DropdownMenuItem, DropdownMenuItemDivider) for building accessible navigation.
• plugins/dropzone/ - Implements drag-and-drop file ingestion with a Redux action lifecycle (dropFileStarted → dropFileSuccess / dropFileFailure) and a React Dropzone component.
• plugins/editor-content-fixtures/ - Ships ten YAML fixture selectors (OpenAPI 2/3, AsyncAPI 2.6/3.0, JSON Schema 2020-12, API Design Systems) for zero-network example loading.
• plugins/editor-content-from-file/ - Extends dropzone and top-bar wrap-actions to route file-drop events into editor content state.
• plugins/editor-content-origin/ - Tracks whether current content came from a URL fetch, file drop, or direct edit; exposes actions and selectors for that origin state.
• plugins/editor-content-persistence/ - Persists editor content to localStorage so content survives page reload.
• plugins/editor-content-read-only/ - Disables all editing surfaces when mounted.
• plugins/editor-content-type/ - Detects and stores the active spec type (OAS2, OAS3, AsyncAPI, etc.) as content changes.
• plugins/editor-monaco/ - Wires Monaco Editor core into the plugin system (model, view state, layout).
• plugins/editor-monaco-language-apidom/ - Registers the ApiDOM language server protocol worker with Monaco for validation and completion.
• plugins/editor-monaco-yaml-paste/ - Intercepts clipboard paste to convert JSON to YAML when appropriate.
• plugins/editor-preview/ - Orchestrates preview panel visibility and panel switching logic.
• plugins/editor-preview-api-design-systems/ - Renders an API Design Systems preview using ApiDOM namespace tooling.
• plugins/editor-preview-asyncapi/ - Renders AsyncAPI specs using @asyncapi/react-component.
• plugins/editor-preview-swagger-ui/ - Renders OpenAPI specs using swagger-ui-react.
• plugins/editor-safe-render/ - Wraps child components in an error boundary to prevent full editor crashes.
• plugins/editor-textarea/ - Provides a plain <textarea> fallback for environments where Monaco cannot load.
• plugins/layout/ - Top-level layout component that positions the editor pane, preview pane, and top bar.
• plugins/modals/ - Manages open/close state for all modals in the system.
• plugins/props-change-watcher/ - Subscribes to React prop changes and re-dispatches them as plugin system events.
• plugins/splash-screen/ - Displays a loading indicator until the editor is fully initialised.
• plugins/swagger-ui-adapter/ - Adapts SwaggerUI's own plugin system so its selectors and actions are accessible from the editor plugin bus.
• plugins/top-bar/ - Renders the File and Edit menus with keyboard shortcuts wired to plugin actions.
• plugins/util/ - Reusable selector helpers and small utilities shared across plugins.
• plugins/versions/ - Exposes selectors reporting the active spec version string.
• presets/ - Bundles plugins into named presets (e.g. the default full-featured preset) for one-line configuration.
• styles/ - Global SCSS variables and entry-point imports.
• types/ - TypeScript ambient declarations for SCSS modules, Monaco, and ApiDOM types.

Common pitfalls and fixes

• Heap OOM during webpack build - Set export NODE_OPTIONS="--max_old_space_size=4096" before running webpack or next build.
• Monaco workers 404 at runtime - Set self.MonacoEnvironment = { baseUrl: '<your-dist-url>/' } before any Monaco import; the path must point to the directory containing apidom.worker.js and editor.worker.js.
• swagger-ui-react/swagger-ui.css missing styles - Import the CSS exactly once at your application entry; omitting it produces an unstyled preview panel with overlapping elements.
• ESM/CJS interop errors with ApiDOM packages - ApiDOM publishes pure ESM; if your bundler emits require() for these modules, add them to webpack resolve.extensionAlias or Vite's ssr.noExternal list.
• GLIBC_2.29 not found on older Linux - The native WASM build requires GLIBC >= 2.29; upgrade the host OS or use the provided Docker image for the build step.
• Plugin order matters for wrap-actions - Plugins that wrap actions (e.g. dropFileSuccessWrap in DropzonePlugin) must be registered after the plugin that owns the original action; reverse order silently swallows the wrap.

Vibe-coding prompt template

I have the Swagger Editor v5 plugin source in `source/` and a usage guide in `USAGE.md`.
The upstream npm package is `user@example.com`.

My project is a [describe your stack: e.g. Next.js 14 / Vite + React / Express + React].
I want to [describe goal: e.g. embed the editor in a dashboard page / add a custom "Load Example" menu item / persist editor content to my backend instead of localStorage].

Please do the following step-by-step:
1. Read `USAGE.md` and the file excerpts to understand the real exports and plugin structure.
2. Identify which plugins from `source/plugins/` I need to import for my goal.
3. Show me exactly where to place the `source/` directory in my project tree.
4. Write the webpack/Vite config changes required (worker entries, polyfills, MonacoEnvironment).
5. Write the integration component(s) using real imports from `source/`, following the patterns in `USAGE.md § Working examples`.
6. Highlight any pitfalls from `USAGE.md § Common pitfalls and fixes` that apply to my stack.
Do not invent plugin names or props; only use symbols documented in USAGE.md.

License and credit

Swagger Editor is released under the Apache License 2.0. See source/LICENSE if present in the block, or refer to the upstream repository. Upstream package: user@example.com maintained by SmartBear / the OpenAPI Initiative.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

AsyncAPI Studio Visual Editor and Design System

Automation, Utilities & Developer Tools

Free