1. Copy the source/ directory into your project, e.g. src/swagger-ui-source/.

2. Configure your bundler (Webpack example) to alias the source root so internal imports like core/plugins/... resolve correctly:

// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      core: path.resolve(__dirname, 'src/swagger-ui-source/core'),
    },
    extensions: ['.js', '.jsx', '.ts', '.tsx'],
  },
};

3. If using TypeScript with tsconfig.json, add path mappings:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "core/*": ["src/swagger-ui-source/core/*"]
    },
    "allowJs": true,
    "jsx": "react"
  }
}

4. If using Babel, ensure @babel/preset-react and @babel/plugin-transform-runtime are configured with corejs: 3.

5. Import the CSS from style/ in your application entry or via your bundler's CSS loader.

6. No environment variables are required by default. The optionsFromQuery source reads from window.location.search at runtime if queryConfigEnabled is set to true.

Public API

SwaggerUI

import SwaggerUI from './swagger-ui-source/index'

SwaggerUI(options: SwaggerUIOptions): SwaggerUIInstance

The main factory function. Call it with a configuration object to mount Swagger UI into a DOM element. Merges defaults, runtime options, and user-provided options, then boots the plugin system. Returns the bound system instance.

typeCastOptions

import { typeCastOptions } from './swagger-ui-source/core/config'

typeCastOptions(options: Record<string, unknown>): Record<string, unknown>

Applies type coercion to a raw options object using the built-in typeCastMappings. Use this when constructing options programmatically before passing them to SwaggerUI, to ensure booleans/arrays are correctly typed rather than remaining as strings from query params.

mergeOptions

import { mergeOptions } from './swagger-ui-source/core/config'

mergeOptions(...optionSets: Record<string, unknown>[]): Record<string, unknown>

Deep-merges multiple option objects in left-to-right priority. Use it to compose defaults, environment-specific overrides, and runtime user options before calling SwaggerUI.

Parameters

import { Parameters } from './swagger-ui-source/core/components/parameters'

The React component responsible for rendering the parameter list for an operation. Use it when building a custom layout plugin that needs to embed the parameter table inside a custom operation wrapper.

optionsFromQuery

import { optionsFromQuery } from './swagger-ui-source/core/config'

optionsFromQuery(): (userOptions: object) => object

Returns a function that reads Swagger UI configuration keys from the current URL query string. Invoke the returned function with the current userOptions to produce a query-derived options overlay.

Working examples

Scenario - Basic DOM mount

Mount Swagger UI into a div using a remote OpenAPI URL, the simplest integration path.

import SwaggerUI from './swagger-ui-source/index'
import './swagger-ui-source/style/main.scss' // or your CSS loader equivalent

SwaggerUI({
  domNode: document.getElementById('swagger-root'),
  url: 'https://petstore3.swagger.io/api/v3/openapi.json',
  deepLinking: true,
  presets: [SwaggerUI.presets.apis],
  layout: 'BaseLayout',
})

Scenario - Inline spec object with merged options

Load a locally bundled OpenAPI spec object, merging environment defaults with runtime overrides.

import SwaggerUI from './swagger-ui-source/index'
import { mergeOptions, typeCastOptions } from './swagger-ui-source/core/config'
import mySpec from './openapi.json'

const baseOptions = {
  deepLinking: false,
  tryItOutEnabled: true,
  supportedSubmitMethods: ['get', 'post'],
}

const runtimeOverrides = {
  tryItOutEnabled: 'false', // arrives as string from some config source
}

const merged = mergeOptions(baseOptions, runtimeOverrides)
const finalOptions = typeCastOptions(merged)

SwaggerUI({
  ...finalOptions,
  domNode: document.getElementById('swagger-root'),
  spec: mySpec,
})

Scenario - Custom plugin extending the system

Register a custom plugin that overrides a single component while keeping all built-in plugins.

import SwaggerUI from './swagger-ui-source/index'

const MyOperationTagPlugin = () => ({
  components: {
    // Replace the built-in OperationTag with a custom wrapper
    OperationTag: ({ tag, children, ...props }: any) => (
      <div className={`my-tag my-tag--${tag}`}>
        <h2>{tag.toUpperCase()}</h2>
        {children}
      </div>
    ),
  },
})

SwaggerUI({
  domNode: document.getElementById('swagger-root'),
  url: '/api/openapi.json',
  plugins: [MyOperationTagPlugin],
  presets: [SwaggerUI.presets.apis],
})

Scenario - Reading options from URL query string

Allow end-users to control the loaded spec URL via a ?url= query parameter.

import SwaggerUI from './swagger-ui-source/index'
import { optionsFromQuery, mergeOptions } from './swagger-ui-source/core/config'

const userOptions = {
  domNode: document.getElementById('swagger-root'),
  queryConfigEnabled: true,
  url: '/api/openapi.json', // default, overridable via ?url=
}

const queryOptions = optionsFromQuery()(userOptions)
const finalOptions = mergeOptions(userOptions, queryOptions)

SwaggerUI(finalOptions)

File walkthrough

• index.js - Thin re-export of SwaggerUI from core/; the public package entry.
• standalone/ - Alternative bundle entry that inlines all dependencies; used for CDN/dist builds.
• style/ - SCSS source for the Swagger UI theme; import or compile separately.
• core/index.js - Bootstraps the plugin system, registers all built-in plugins and presets, exposes SwaggerUI.presets and SwaggerUI.config.
• core/system.js - Plugin registry and system factory; manages component overrides, action/selector binding, and Redux store construction.
• core/config/ - Exports defaultOptions, mergeOptions, typeCastOptions, typeCastMappings, optionsFromQuery, optionsFromURL, optionsFromRuntime, inlinePluginOptionsFactorization, systemOptionsFactorization.
• core/components/ - All leaf and container React components for rendering operations, parameters, auth flows, responses, models, and layout.
• core/components/auth/ - Auth-specific components: OAuth2, API key, Basic auth, authorization popup.
• core/components/layouts/ - BaseLayout and StandaloneLayout top-level layout shells.
• core/components/parameters/ - Parameters component; exported via index.js.
• core/components/providers/ - React context providers wiring the system into the component tree.
• core/plugins/ - Each file is a self-contained plugin (auth, spec, oas3, layout, filter, deep-linking, syntax-highlighting, versions, safe-render, etc.).
• core/presets/ - BasePreset and ApisPreset group built-in plugins into named collections.
• core/containers/ - Redux-connected wrappers around core components.
• core/utils/ - Pure utility helpers (URL parsing, sanitization, immutable helpers, etc.).
• core/assets/ - rolling-load.svg loading spinner and other static assets.
• core/oauth2-authorize.js - Handles the OAuth2 redirect/callback window logic.
• core/window.js - Provides a safe window reference that degrades gracefully in SSR environments.

Common pitfalls and fixes

• core/ alias not resolved: Internal imports use bare core/... paths; configure a Webpack alias or tsconfig path mapping pointing to src/swagger-ui-source/core/ or the build will fail with module-not-found errors.
• JSX not transpiled: The source uses .jsx files; ensure your Babel or TSC config includes @babel/preset-react or "jsx": "react" / "react-jsx", otherwise you will get parse errors.
• Immutable.js version mismatch: Swagger UI requires user@example.com; installing user@example.com causes runtime type errors in selectors. Pin "immutable": "^4.0.0".
• DOMPurify not available in SSR/Node: dompurify requires a DOM; in SSR contexts guard rendering with core/window.js patterns or use isomorphic-dompurify.
• CSS not loaded: The JS bundle does not auto-inject styles; you must import style/main.scss (or its compiled CSS equivalent) separately, or operation blocks will render unstyled.
• @babel/runtime-corejs3 missing: The source uses @babel/runtime-corejs3 helpers; if your build strips or externalizes Babel runtime without corejs3, you will get Cannot find module '@babel/runtime-corejs3/...' at runtime. Install it explicitly.

Vibe-coding prompt template

I have purchased an AVCP block that provides the full source of user@example.com
under `source/` in my project. I also have `USAGE.md` which is the integration guide.

Please read `USAGE.md` and the files under `source/` (entry point is `source/index.js`,
core logic is in `source/core/`), then integrate Swagger UI into my existing project
step by step:

1. Configure my bundler (Webpack / Vite / tsconfig) to resolve the `core/` alias
   so that internal `core/...` imports in the source work correctly.
2. Install all required npm dependencies listed in USAGE.md.
3. Add a page or route in my app that mounts SwaggerUI into a DOM node, loading
   my OpenAPI spec from `/api/openapi.json`.
4. Import the styles from `source/style/` so the UI is correctly themed.
5. Show me how to pass a custom plugin that overrides one built-in component.

Use only the real exports documented in USAGE.md (`SwaggerUI`, `mergeOptions`,
`typeCastOptions`, `optionsFromQuery`, `Parameters`). Do not invent new APIs.
Reference the upstream package as `swagger-ui` version 5.32.4.

License and credit

Swagger UI is released under the Apache License 2.0. See source/LICENSE if present in the bundle, or review the canonical license at the upstream repository. Upstream package: swagger-ui by SmartBear / the OpenAPI Initiative. Source repository: github.com/swagger-api/swagger-ui.

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.