Swagger UI

https://github.com/swagger-api/swagger-ui
Admin
Swagger UI allows developers to visualize and interact with API resources through automatically...
Tokens:48,511
Snippets:396
Trust Score:7.8
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Clone, install, and run Swagger UI development server

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Sets up the Swagger UI repository, installs dependencies, initializes Husky, and starts the hot-reloading Webpack dev server on port 3200.

```bash
# Clone the repository
git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui

# Install dependencies
npm install

# Initialize Husky (optional, for git hooks)
npx husky init

# Start development server
npm run dev

# Open http://localhost:3200/
```

--------------------------------

### Clone, install, and run the SwaggerUI dev server

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/development/setting-up.md

Commands to clone the repository, install dependencies, optionally initialize Husky, and start the development server with hot module reloading. Requires Node.js >=24.22 and npm >=11.19.1. After running, open http://localhost:3200/.

```bash
git clone https://github.com/swagger-api/swagger-ui.git
```

```bash
cd swagger-ui
```

```bash
npm install
```

```bash
npx husky init
```

```bash
npm run dev
```

--------------------------------

### Use samples API with swagger-ui package

Source: https://github.com/swagger-api/swagger-ui/wiki/JSON-Schema-samples-API

Initialize the samples API statically using the swagger-ui package. Requires installing swagger-ui and importing the JSONSchema5Samples and JSONSchema202012Samples plugins. The example calls getJsonSampleSchema on both jsonSchema5 and jsonSchema202012 to generate sample JSON from a simple object schema.

```js
import SwaggerUI from 'swagger-ui';

const system = new SwaggerUI.System({ 
  plugins: [
   SwaggerUI.plugins.JSONSchema5Samples,
   SwaggerUI.plugins.JSONSchema202012Samples 
  ],
  presets: [],
}).getSystem();

system.fn.jsonSchema5.getJsonSampleSchema({ type: "object", properties: { a: { type: "string" }} });
system.fn.jsonSchema202012.getJsonSampleSchema({ type: "object", properties: { a: { type: "string" }} });
```

--------------------------------

### Use samples API with swagger-ui-react package

Source: https://github.com/swagger-api/swagger-ui/wiki/JSON-Schema-samples-API

Initialize the samples API statically using the swagger-ui-react package. Requires installing swagger-ui-react and importing the JSONSchema5Samples and JSONSchema202012Samples plugins. The example calls getJsonSampleSchema on both jsonSchema5 and jsonSchema202012 to generate sample JSON from a simple object schema.

```js
import SwaggerUI from 'swagger-ui-react';

const system = new SwaggerUI.System({ 
  plugins: [
   SwaggerUI.plugins.JSONSchema5Samples,
   SwaggerUI.plugins.JSONSchema202012Samples 
  ],
  presets: [],
}).getSystem();

system.fn.jsonSchema5.getJsonSampleSchema({ type: "object", properties: { a: { type: "string" }} });
system.fn.jsonSchema202012.getJsonSampleSchema({ type: "object", properties: { a: { type: "string" }} });
```

--------------------------------

### Full plugin example with statePlugins, components, and fn

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/add-plugin.md

A complete example of a Swagger-UI plugin factory. It demonstrates statePlugins (actions, wrapActions, reducers, selectors), components, and fn. The factory receives a toolbox argument that includes the plugin system and Immutable reference.

```javascript
// A contrived, but quite full example....

export function SomePlugin(toolbox) {

  const UPDATE_SOMETHING = "some_namespace_update_something" // strings just need to be uniuqe... see below

  // Tools
  const fromJS = toolbox.Im.fromJS // needed below
  const createSelector = toolbox.createSelector // same, needed below

  return {
    statePlugins: {

      someNamespace: {
        actions: {
          actionName: (args)=> ({type: UPDATE_SOMETHING, payload: args}), // Synchronous action must return an object for the reducer to handle
          anotherAction: (a,b,c) => (system) => system.someNamespaceActions.actionName(a || b) // Asynchronous actions must return a function. The function gets the whole system, and can call other actions (based on state if needed)
        },
        wrapActions: {
          anotherAction: (oriAction, system) => (...args) => {
            oriAction(...args) // Usually we at least call the original action
            system.someNamespace.actionName(...args) // why not call this?
            console.log("args", args) // Log the args
            // anotherAction in the someNamespace has now been replaced with the this function
          }
        },
        reducers: {
          [UPDATE_SOMETHING]: (state, action) => { // Take a state (which is immutable) and an action (see synchronous actions) and return a new state
            return state.set("something", fromJS(action.payload)) // we're updating the Immutable state object... we need to convert vanilla objects into an immutable type (fromJS)
            // See immutable about how to modify the state
            // PS: you're only working with the state under the namespace, in this case "someNamespace". So you can do what you want, without worrying about /other/ namespaces
          }
        },
        selectors: {
          // creatSelector takes a list of fn's and passes all the results to the last fn.
          // eg: createSelector(a => a, a => a+1, (a,a2) => a + a2)(1) // = 3
          something: createSelector( // see [reselect#createSelector](https://github.com/reactjs/reselect#createselectorinputselectors--inputselectors-resultfunc)
            getState => getState(), // This is a requirement... because we `bind` selectors, we don't want to bind to any particular state (which is an immutable value) so we bind to a function, which returns the current state
            state => state.get("something") // return the whatever "something" points to
          ),
          foo: getState => "bar" // In the end selectors are just functions that we pass getState to
        }
      }

      ... // you can include as many namespaces as you want. They just get merged into the 'system'

    },

    components: {
      foo: ()=> <h1> Hello </h1> // just a map of names to react components, naturally you'd want to import a fuller react component
    },

    fn: {
      addOne: (a) => a + 1 // just any extra functions you want to include
    }
  }
}
```

--------------------------------

### Install swagger-ui-dist via npm

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Install the swagger-ui-dist package for server-side projects.

```sh
 $ npm install swagger-ui-dist 
```

--------------------------------

### Run Development Server

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Starts the development server with hot reload and unminified stack traces. Access the app at http://localhost:3200/.

```bash
npm run dev
# Open http://localhost:3200/
# Hot reload enabled
# Unminified stack traces
```

--------------------------------

### Start Mock API Server for E2E

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Starts the JSON Server mock API on port 3204, used by E2E tests.

```bash
npm run e2e:mock-api  # JSON Server on port 3204
```

--------------------------------

### Essential npm Commands for Development, Building, Testing, and Linting

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Lists common npm scripts for development, building, testing, linting, security auditing, and dependency checks. Use `npm run dev` to start the dev server on port 3200, `npm start` for the static file server on port 3002, and `npm test` to run the full test suite (lint + unit + E2E).

```bash
# Development
npm run dev              # Start dev server (port 3200)
npm start                # Static file server (port 3002)

# Building
npm run build            # Full production build
npm run clean            # Remove dist/

# Testing
npm test                 # Full test suite (lint + unit + E2E)
npm run test:unit        # Jest unit tests
npm run e2e              # Playwright E2E
npm run e2e:ui           # Playwright interactive
npm run test:artifact    # Artifact verification

# Linting
npm run lint             # ESLint (errors + warnings)
npm run lint-errors      # ESLint (errors only)
npm run lint-fix         # Auto-fix ESLint issues
npm run lint-styles      # Stylelint
npm run lint-styles-fix  # Auto-fix Stylelint issues

# Security
npm run security-audit   # Run npm audit

# Dependencies
npm run deps-check       # Size and license report
```

--------------------------------

### Install swagger-ui-react via npm

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Install the swagger-ui-react package for React projects.

```sh
 $ npm install swagger-ui-react 
```

--------------------------------

### Install swagger-ui via npm

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Install the swagger-ui package for JavaScript projects with module bundlers.

```sh
 $ npm install swagger-ui 
```

--------------------------------

### String environment variables example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/configuration.md

Set string configuration parameters via environment variables in Docker. Escape characters as necessary.

```sh
FILTER="myFilterValue"
LAYOUT="BaseLayout"
```

--------------------------------

### Number environment variables example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/configuration.md

Set numeric configuration parameters via environment variables in Docker. Provide the number as the value.

```sh
DEFAULT_MODELS_EXPAND_DEPTH="5"
DEFAULT_MODEL_EXPAND_DEPTH="7"
```

--------------------------------

### Example Plugin Directory Structure (oas32)

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Shows the recommended self-contained layout for an OAS version plugin, with components, wrap-components, and fn.js kept within the plugin to avoid cross-plugin imports.

```text
src/core/plugins/oas32/
├── json-schema-2020-12-extensions/
│   ├── components/              # Self-contained components
│   │   └── keywords/
│   │       ├── Description.jsx
│   │       └── Properties.jsx
│   ├── wrap-components/         # Wrappers for components
│   │   └── keywords/
│   │       ├── Description.jsx  # Imports from ../../components/
│   │       └── Properties.jsx   # Not from ../../../../oas31/
│   └── fn.js                    # Self-contained utilities
```

--------------------------------

### Object environment variables example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/configuration.md

Set object configuration parameters via environment variables in Docker. Provide the literal object value, escaping characters as necessary.

```sh
SPEC="{ \"openapi\": \"3.0.4\" }"
```

--------------------------------

### Boolean environment variables example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/configuration.md

Set boolean configuration parameters via environment variables in Docker. Use 'true' or 'false' as the value.

```sh
DISPLAY_OPERATION_ID="true"
DEEP_LINKING="false"
```

--------------------------------

### Set SCARF_ANALYTICS environment variable to false

Source: https://github.com/swagger-api/swagger-ui/blob/main/swagger-ui-dist-package/README.md

Use this command to opt out of Scarf analytics by setting the SCARF_ANALYTICS environment variable to false during installation. Example: SCARF_ANALYTICS=false npm install.

```shell
SCARF_ANALYTICS=false npm install
```

--------------------------------

### Array environment variables example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/configuration.md

Set array configuration parameters via environment variables in Docker. Provide the literal array value, escaping characters as necessary.

```sh
SUPPORTED_SUBMIT_METHODS="[\"get\", \"post\"]"
URLS="[ { url: \"https://petstore.swagger.io/v2/swagger.json\", name: \"Petstore\" } ]"
```

--------------------------------

### Action plugin example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Defines an action creator that returns a Flux Standard Action, which will be passed to the reducer.

```javascript
const MyActionPlugin = () => {
  return {
    statePlugins: {
      example: {
        actions: {
          updateFavoriteColor: (str) => {
            return {
              type: "EXAMPLE_SET_FAV_COLOR",
              payload: str
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Docker-Compose .env file example encoding

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/configuration.md

Example of encoding environment variables in a Docker-Compose .env file. Uses single quotes for values.

```sh
SUPPORTED_SUBMIT_METHODS=['get', 'post']
URLS=[ { url: 'https://petstore.swagger.io/v2/swagger.json', name: 'Petstore' } ]
```

--------------------------------

### Reducer plugin example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Defines a reducer that handles the action type and updates the state using Immutable.js.

```javascript
const MyReducerPlugin = function(system) {
  return {
    statePlugins: {
      example: {
        reducers: {
          "EXAMPLE_SET_FAV_COLOR": (state, action) => {
            // you're only working with the state under the namespace, in this case "example".
            // So you can do what you want, without worrying about /other/ namespaces
            return state.set("favColor", action.payload)
          }
        }
      }
    }
  }
}
```

--------------------------------

### CORS header parameters example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/cors.md

Header names that must be supported in your CORS configuration for Swagger UI to send them as parameters.

```text
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
```

--------------------------------

### Get absolute filesystem path with getAbsoluteFSPath

Source: https://github.com/swagger-api/swagger-ui/blob/main/swagger-ui-dist-package/README.md

Use the exported getAbsoluteFSPath method to get an absolute path to the dist directory for static file serving. The returned path is then used to instantiate a server that serves files from that directory.

```javascript
const swaggerUiAssetPath = require("swagger-ui-dist").getAbsoluteFSPath()

// then instantiate server that serves files from the swaggerUiAssetPath
```

--------------------------------

### Run All E2E Tests with Playwright

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Runs the full E2E test suite, automatically starting the webpack dev server and mock API.

```bash
# Run all E2E tests (starts webpack dev server + mock API automatically)
npm run e2e
```

--------------------------------

### Example commit message

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Shows a valid commit message following the Conventional Commits format, including a type, scope, subject, body, and footer referencing an issue.

```text
feat(oas3): add support for OpenAPI 3.1.1 callbacks

Implement callback rendering for OAS 3.1.1 specifications
with proper schema resolution and example generation.

Fixes #12345
```

--------------------------------

### Run a single Playwright e2e spec

Source: https://github.com/swagger-api/swagger-ui/blob/main/README.md

Run a single end-to-end test spec with npm run e2e, passing the spec file path. Requires Playwright browser installed via npx playwright install chromium.

```sh
npm run e2e -- test/e2e-playwright/features/deep-linking.spec.ts
```

--------------------------------

### Run a Single E2E Spec

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Runs a specific Playwright test spec file, for example the deep-linking feature test.

```bash
# Run one spec
npm run e2e -- test/e2e-playwright/features/deep-linking.spec.ts
```

--------------------------------

### Opt out of Scarf analytics via package.json (scarfSettings.enabled)

Source: https://github.com/swagger-api/swagger-ui/blob/main/swagger-ui-dist-package/README.md

Add this to your project's package.json to disable Scarf analytics, which run during installation. The field must be set to false to opt out.

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

--------------------------------

### Configure OAuth 2.0 with initOAuth

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/oauth2.md

Call this method after constructing SwaggerUIBundle to set OAuth 2.0 parameters such as clientId, scopes, and PKCE. The example enables basic authentication for access code grant and PKCE for authorization code grant.

```javascript
const ui = SwaggerUI({...})

// Method can be called in any place after calling constructor SwaggerUIBundle
ui.initOAuth({
    clientId: "your-client-id",
    clientSecret: "your-client-secret-if-required",
    realm: "your-realms",
    appName: "your-app-name",
    scopeSeparator: " ",
    scopes: "openid profile",
    additionalQueryStringParams: {test: "hello"},
    useBasicAuthenticationWithAccessCodeGrant: true,
    usePkceWithAuthorizationCodeGrant: true
  })
```

--------------------------------

### Run Jest Watch Mode

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Starts Jest in watch mode to re-run tests on file changes and filter by file or test name.

```bash
npm run test:unit -- --watch
# Re-run on file changes
# Filter by file name or test name
```

--------------------------------

### Example transformer: increase line numbers by 10

Source: https://github.com/swagger-api/swagger-ui/blob/main/src/core/plugins/err/error-transformers/README.md

This transformer maps over the errors and increments the 'line' property by 10. It must preserve all keys in each error map.

```javascript
export function transform(errors) {
  return errors.map(err => {
    err.line += 10
    return err
  })
}
```

--------------------------------

### Date format schema example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plug-points.md

YAML schema definition for a string with format 'date'. The resulting component name is JsonSchema_string_date.

```yaml
type: string
format: date
```

--------------------------------

### Date-time format schema example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plug-points.md

YAML schema definition for a string with format 'date-time'. The resulting component name is JsonSchema_string_date-time.

```yaml
type: string
format: date-time
```

--------------------------------

### Get a container component via getComponent

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/overview.md

Use the injected getComponent helper to retrieve components as a container, passing 'true' as the second argument to map the current system as props to the component.

```javascript
getComponent("ContainerComponentName", true)
```

--------------------------------

### Swagger UI 2.x version comment in swagger-ui.js

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/version-detection.md

In Swagger UI 2.x and under, the exact version is found in a comment at the top of the `swagger-ui.js` file. This example shows version 2.2.9.

```javascript
/**
 * swagger-ui - Swagger UI is a dependency-free collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API
 * @version v2.2.9
 * @link https://swagger.io
 * @license Apache-2.0
 */
```

--------------------------------

### Custom Fallback plugin example

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plug-points.md

Shows how to override the Fallback component with a custom implementation. The plugin is added to SwaggerUI plugins array.

```javascript
const CustomFallbackPlugin = () => ({
  components: {
    Fallback: ({ name } ) => `This is my custom fallback. ${name} failed to render`,
  },
});

const swaggerUI = SwaggerUI({
  url: "https://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  plugins: [
    CustomFallbackPlugin,
  ]  
});
```

--------------------------------

### Wrap-Components: Override a component with function and class wrappers

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Provides a complete example: a base component (NumberDisplay) and two alternative wrappers—one as a function and one as a class—that add a warning when the number exceeds 10. The class wrapper uses React.component (note: likely a typo for React.Component).

```javascript
/////  Overriding a component from a plugin

// Here's our normal, unmodified component.
const MyNumberDisplayPlugin = function(system) {
  return {
    components: {
      NumberDisplay: ({ number }) => <span>{number}</span>
    }
  }
}

// Here's a component wrapper defined as a function.
const MyWrapComponentPlugin = function(system) {
  return {
    wrapComponents: {
      NumberDisplay: (Original, system) => (props) => {
        if(props.number > 10) {
          return <div>
            <h3>Warning! Big number ahead.</h3>
            <Original {...props} />
          </div>
        } else {
          return <Original {...props} />
        }
      }
    }
  }
}

// Alternatively, here's the same component wrapper defined as a class.
const MyWrapComponentPlugin = function(system) {
  return {
    wrapComponents: {
      NumberDisplay: (Original, system) => class WrappedNumberDisplay extends React.component {
        render() {
          if(props.number > 10) {
            return <div>
              <h3>Warning! Big number ahead.</h3>
              <Original {...props} />
            </div>
          } else {
            return <Original {...props} />
          }
        }
      }
    }
  }
}
```

--------------------------------

### Docker commands to pull and run Swagger UI

Source: https://github.com/swagger-api/swagger-ui/wiki/For-dummies,-part-1:-installing-as-proxy-at-your-Nginx

These commands pull the Swagger UI Docker image and run it, mapping host port 80 to container port 8080. The '&' at the end preserves the service after closing the terminal. The service starts Nginx with Swagger UI on port 80.

```sh
docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui &
```

--------------------------------

### SwaggerUI.System.getSystem

Source: https://github.com/swagger-api/swagger-ui/wiki/JSON-Schema-samples-API

Creates a SwaggerUI system instance for static usage of the samples API. This is the entry point to access the samples API methods.

```APIDOC
## [SwaggerUI.System] [getSystem]

### Description
Creates a SwaggerUI system instance that provides access to the samples API through `system.fn`.

### Method
Constructor call

### Endpoint
`new SwaggerUI.System({ plugins, presets }).getSystem()`

### Parameters
#### Constructor Options
- **plugins** (array) - Required - Array of SwaggerUI plugins. Must include `SwaggerUI.plugins.JSONSchema5Samples` and/or `SwaggerUI.plugins.JSONSchema202012Samples` to enable the samples API.
- **presets** (array) - Required - Array of presets. Set to `[]` for static usage.

### Request Example
```js
const system = new SwaggerUI.System({ 
  plugins: [
   SwaggerUI.plugins.JSONSchema5Samples,
   SwaggerUI.plugins.JSONSchema202012Samples 
  ],
  presets: [],
}).getSystem();
```

### Response
#### Success Response
Returns a system object with `fn` property containing the samples API methods.

#### Response Example
```js
system.fn.jsonSchema5.getJsonSampleSchema({ type: "object", properties: { a: { type: "string" }} });
system.fn.jsonSchema202012.getJsonSampleSchema({ type: "object", properties: { a: { type: "string" }} });
```
```

--------------------------------

### Detect Swagger UI 3.x version via console

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/version-detection.md

Open the browser's web console and execute this command to get the version object. The result will look like `swaggerUi : Object { version: "3.1.6", gitRevision: "g786cd47", gitDirty: true, … }`. This functionality was added in 3.0.8; if it fails, you likely have an older version.

```javascript
JSON.stringify(versions)
```

--------------------------------

### Test your changes

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Run unit tests, interactive E2E testing, build verification, and artifact verification.

```bash
npm run test:unit     # Run unit tests
npm run e2e:ui        # Interactive E2E testing
npm run build         # Verify build works
npm run test:artifact # Verify artifacts
```

--------------------------------

### Provide components to the system

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Provides a map of components to integrate into the system. Be mindful of the key names, as they are used to refer to the components elsewhere.

```javascript
class HelloWorldClass extends React.Component {
  render() {
    return <h1>Hello World!</h1>
  }
}

const MyComponentPlugin = function(system) {
  return {
    components: {
      HelloWorldClass: HelloWorldClass
      // components can just be functions, these are called "stateless components"
      HelloWorldStateless: () => <h1>Hello World!</h1>,
    }
  }
}
```

--------------------------------

### Project File Paths

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Shows the key file and directory paths in the Swagger UI project, including the core system, entry points, components, plugins, styles, tests, and build output.

```text
Core System:           src/core/system.js
Main Entry:            src/index.js
React Entry:           flavors/swagger-ui-react/index.jsx
Components:            src/core/components/
Plugins:               src/core/plugins/
Styles:                src/style/
Tests (Unit):          test/unit/
Tests (E2E):           test/e2e-playwright/
Build Output:          dist/
```

--------------------------------

### fn: Add a helper function to the system

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Shows how to add a helper function (leftPad) to the system's fn interface, making it available for use elsewhere.

```javascript
import leftPad from "left-pad"

const MyFnPlugin = function(system) {
  return {
    fn: {
      leftPad: leftPad
    }
  }
}
```

--------------------------------

### Basic usage of SwaggerUI

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Import SwaggerUI and initialize it with a DOM element ID. Use either import or require.

```javascript
import SwaggerUI from 'swagger-ui'
// or use require if you prefer
const SwaggerUI = require('swagger-ui')

SwaggerUI({
  dom_id: '#myDomId'
})
```

--------------------------------

### rootInjects: Inject values into the top-level system

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Shows how to add a constant and a method to the system's root object via the rootInjects interface. The injected values become available at runtime.

```javascript
const MyRootInjectsPlugin = function(system) {
  return {
    rootInjects: {
      myConstant: 123,
      myMethod: (...params) => console.log(...params)
    }
  }
}
```

--------------------------------

### Run Docker with local swagger.json

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Provide your own swagger.json on your host using SWAGGER_JSON and volume mount.

```sh
docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo docker.swagger.io/swaggerapi/swagger-ui
```

--------------------------------

### Verify bug fix

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Run unit tests, build, and artifact verification to confirm a bug fix works.

```bash
npm run test:unit
npm run build
npm run test:artifact
```

--------------------------------

### Embed Swagger UI with StandalonePreset via unpkg

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

HTML page that adds the standalone preset to render the TopBar and ValidatorBadge. It loads the standalone preset script and configures the layout as `StandaloneLayout`.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="SwaggerUI" />
    <title>SwaggerUI</title>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
  </head>
  <body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
  <script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js" crossorigin></script>
  <script>
    window.onload = () => {
      window.ui = SwaggerUIBundle({
        url: 'https://petstore3.swagger.io/api/v3/openapi.json',
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "StandaloneLayout",
      });
    };
  </script>
  </body>
</html>
```

--------------------------------

### JavaScript to initialize Swagger UI

Source: https://github.com/swagger-api/swagger-ui/blob/main/test/e2e-selenium/static/index.html

JavaScript that builds and initializes the Swagger UI bundle with a URL, presets, plugins, layout, and OAuth configuration. It also sets up a completion counter and exposes the UI instance globally.

```javascript
window.onload = function() {
  window["SwaggerUIBundle"] = window["swagger-ui-bundle"]
  window["SwaggerUIStandalonePreset"] = window["swagger-ui-standalone-preset"]
  // Build a system
  const ui = SwaggerUIBundle({
    url: "",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout",
    onComplete: () => {
      if(window.completeCount) {
        window.completeCount++
      } else {
        window.completeCount = 1
      }
    }
  })
  window.ui = ui
  ui.initOAuth({
    clientId: "your-client-id",
    clientSecret: "your-client-secret-if-required",
    realm: "your-realms",
    appName: "your-app-name",
    scopeSeparator: " ",
    scopes: "read:pets profile openid",
    additionalQueryStringParams: {}
  })
}
```

--------------------------------

### Extending plugin using system

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Shows how a plugin can access the system object to call actions from another plugin, requiring the other plugin to be loaded first.

```javascript
const ExtendingPlugin = function(system) {
  return {
    statePlugins: {
      extending: {
        actions: {
          doExtendedThings: function(...args) {
            // you can do other things in here if you want
            return system.normalActions.doStuff(...args)
          }
        }
      }
    }
  }
}
```

--------------------------------

### Clone swagger-ui repository

Source: https://github.com/swagger-api/swagger-ui/wiki/For-dummies,-part-2:-rebuild-docker-image

Clone the swagger-ui repository into the home directory before making changes and rebuilding the Docker image.

```sh
cd ~
git clone https://github.com/swagger-api/swagger-ui.git
```

--------------------------------

### Pull and run Swagger UI Docker image

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Pull the pre-built Docker image and run it on port 80.

```sh
docker pull docker.swagger.io/swaggerapi/swagger-ui
docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui
```

--------------------------------

### Run Complete Test Suite

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Runs the full test suite: lint-errors, unit tests, and E2E tests.

```bash
npm test  # Runs: lint-errors + test:unit + e2e
```

--------------------------------

### afterLoad: Attach a bound action as a top-level method

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Demonstrates using afterLoad to attach a bound action (updateFavoriteColor) to the system's rootInjects. The plugin also defines the action in its statePlugins.

```javascript
const MyMethodProvidingPlugin = function() {
  return {
    afterLoad(system) {
      // at this point in time, your actions have been bound into the system
      // so you can do things with them
      this.rootInjects = this.rootInjects || {}
      this.rootInjects.myMethod = system.exampleActions.updateFavoriteColor
    },
    statePlugins: {
      example: {
        actions: {
          updateFavoriteColor: (str) => {
            return {
              type: "EXAMPLE_SET_FAV_COLOR",
              payload: str
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Instance Methods

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/configuration.md

Methods available on the Swagger UI instance for programmatic control of OAuth and authorization.

```APIDOC
## Instance Methods

### initOAuth
- **Signature**: `(configObj) => void`
- **Docker Variable**: [_See `oauth2.md`_](./oauth2.md)
- **Description**: Provide Swagger UI with information about your OAuth server - see the OAuth 2.0 documentation for more information.

### preauthorizeBasic
- **Signature**: `(authDefinitionKey, username, password) => action`
- **Docker Variable**: _Unavailable_
- **Description**: Programmatically set values for a Basic authorization scheme.

### preauthorizeApiKey
- **Signature**: `(authDefinitionKey, apiKeyValue) => action`
- **Docker Variable**: _Unavailable_
- **Description**: Programmatically set values for an API key or Bearer authorization scheme. In case of OpenAPI 3.0 Bearer scheme, `apiKeyValue` must contain just the token itself without the `Bearer` prefix.
```

--------------------------------

### CORS error message in debug console

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/cors.md

Example error message seen in the browser debug console when CORS is not enabled. Swagger UI cannot easily show this error state.

```text
XMLHttpRequest cannot load http://sad.server.com/v2/api-docs. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'null' is therefore not allowed access.
```

--------------------------------

### Build commands for Swagger UI

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Commands to build stylesheets and all bundles, including individual builds for core, bundle, standalone, ES module bundles, and CSS. Use npm run clean to remove build artifacts.

```bash
# Full build (stylesheets + all bundles)
npm run build

# Individual builds
npm run build:core              # Core bundle (browser)
npm run build:bundle            # Isomorphic bundle
npm run build:standalone        # Standalone preset
npm run build:es:bundle         # ES module bundle
npm run build:es:bundle:core    # ES module core
npm run build-stylesheets       # CSS only

# Clean build artifacts
npm run clean
```

--------------------------------

### Plugin return value format

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Shows the keys a plugin can return, including statePlugins, components, wrapComponents, rootInjects, afterLoad, and fn.

```javascript
{
  statePlugins: {
    [stateKey]: {
      actions,
      reducers,
      selectors,
      wrapActions,
      wrapSelectors
    }
  },
  components: {},
  wrapComponents: {},
  rootInjects: {},
  afterLoad: (system) => {},
  fn: {},
}
```

--------------------------------

### Replace default petstore URL in dev-helper-initializer.js

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/development/setting-up.md

Replace the default remote API URL with a local file path in dev-helpers/dev-helper-initializer.js. The local file must be inside the dev-helpers directory or a subdirectory; the recommended location is dev-helpers/examples.

```javascript
url: "https://petstore.swagger.io/v2/swagger.json",
```

```javascript
url: "./examples/your-local-api-definition.yaml",
```

--------------------------------

### Embed Swagger UI via unpkg (basic)

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Basic HTML page that loads Swagger UI from unpkg and initializes it with a URL to an OpenAPI document. The `dom_id` targets the `#swagger-ui` div.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="description" content="SwaggerUI" />
  <title>SwaggerUI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
      dom_id: '#swagger-ui',
    });
  };
</script>
</body>
</html>
```

--------------------------------

### Replace Logo component via plugin API

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plug-points.md

Exchange the default SwaggerUI logo in the Standalone Preset's Top Bar by providing a custom Logo component through the plugin API. The example renders an image with a base64-encoded SVG data URI.

```jsx
import React from "react";
const MyLogoPlugin = {
  components: {
    Logo: () => (
      <img alt="My Logo" height="40" src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNTM3IiBoZWlnaHQ9IjEzNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCiA8Zz4KICA8dGl0bGU+TGF5ZXIgMTwvdGl0bGU+CiAgPHRleHQgdHJhbnNmb3JtPSJtYXRyaXgoMy40Nzc2OSAwIDAgMy4yNjA2NyAtNjczLjEyOCAtNjkxLjk5MykiIHN0cm9rZT0iIzAwMCIgZm9udC1zdHlsZT0ibm9ybWFsIiBmb250LXdlaWdodD0ibm9ybWFsIiB4bWw6c3BhY2U9InByZXNlcnZlIiB0ZXh0LWFuY2hvcj0ic3RhcnQiIGZvbnQtZmFtaWx5PSInT3BlbiBTYW5zIEV4dHJhQm9sZCciIGZvbnQtc2l6ZT0iMjQiIGlkPSJzdmdfMSIgeT0iMjQxLjIyMTkyIiB4PSIxOTYuOTY5MjEiIHN0cm9rZS13aWR0aD0iMCIgZmlsbD0iIzYyYTAzZiI+TXkgTG9nbzwvdGV4dD4KICA8cGF0aCBpZD0ic3ZnXzIiIGQ9Im0zOTUuNjAyNSw1MS4xODM1OWw1My44Nzc3MSwwbDE2LjY0ODYzLC01MS4xODM1OGwxNi42NDg2NCw1MS4xODM1OGw1My44Nzc3LDBsLTQzLjU4NzksMzEuNjMyODNsMTYuNjQ5NDksNTEuMTgzNThsLTQzLjU4NzkyLC0zMS42MzM2OWwtNDMuNTg3OTEsMzEuNjMzNjlsMTYuNjQ5NDksLTUxLjE4MzU4bC00My41ODc5MiwtMzEuNjMyODN6IiBzdHJva2Utd2lkdGg9IjAiIHN0cm9rZT0iIzAwMCIgZmlsbD0iIzYyYTAzZiIvPgogPC9nPgo8L3N2Zz4="/>
    )
  }
}
```

--------------------------------

### Run Docker with BASE_URL

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Change the base URL of the web application using BASE_URL environment variable.

```sh
docker run -p 80:8080 -e BASE_URL=/swagger -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo docker.swagger.io/swaggerapi/swagger-ui
```

--------------------------------

### Run Artifact Tests

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Runs the artifact test suite to verify build artifacts export correctly.

```bash
npm run test:artifact
```

--------------------------------

### Macros Configuration Parameters

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/configuration.md

Configuration parameters for setting default values in models and parameters.

```APIDOC
## Configuration Parameters

### modelPropertyMacro
- **Type**: Function
- **Docker Variable**: _Unavailable_
- **Description**: Function to set default values to each property in model. Accepts one argument `modelPropertyMacro(property)`, property is immutable.

### parameterMacro
- **Type**: Function
- **Docker Variable**: _Unavailable_
- **Description**: Function to set default value to parameters. Accepts two arguments `parameterMacro(operation, parameter)`. Operation and parameter are objects passed for context, both remain immutable.
```

--------------------------------

### Add a plugin to SwaggerUI config

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/add-plugin.md

Shows how to include a plugin in the Swagger-UI configuration by passing an array of plugins to the SwaggerUI function.

```javascript
SwaggerUI({
  url: 'some url',
  plugins: [ ... ]
})
```

--------------------------------

### Prettier Configuration (.prettierrc.yaml)

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Defines Prettier settings: no semicolons, ES5 trailing commas, LF line endings, and requires the @prettier pragma. The pragma must be present at the top of files for formatting to apply.

```yaml
semi: false              # No semicolons
trailingComma: es5       # ES5 trailing commas
endOfLine: lf            # Unix line endings
requirePragma: true      # Require @prettier pragma
insertPragma: true       # Insert @prettier pragma

```

--------------------------------

### Retrieve components with getComponent

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Retrieves components from the system using the keys defined in the component plugin. Use this to access components elsewhere in the application.

```javascript
// elsewhere
const HelloWorldStateless = system.getComponent("HelloWorldStateless")
const HelloWorldClass = system.getComponent("HelloWorldClass")
```

--------------------------------

### Serve Swagger UI static files with Express

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Use swagger-ui-dist's absolutePath() to serve the static assets with Express.

```javascript
const express = require('express')
const pathToSwaggerUi = require('swagger-ui-dist').absolutePath()

const app = express()

app.use(express.static(pathToSwaggerUi))

app.listen(3000)
```

--------------------------------

### Run Playwright UI Mode

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Launches the Playwright visual test runner with time-travel debugging and network inspection.

```bash
npm run e2e:ui
# Visual test runner
# Time-travel debugging with traces
# Network inspection
```

--------------------------------

### Run Docker with external swagger.json URL

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

Provide a URL to a swagger.json on an external host using SWAGGER_JSON_URL.

```sh
docker run -p 80:8080 -e SWAGGER_JSON_URL=https://petstore3.swagger.io/api/v3/openapi.json docker.swagger.io/swaggerapi/swagger-ui
```

--------------------------------

### Wrap-Selectors: Override a selector with a wrapper function

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Shows how to define a plugin with a selector and then wrap it to log when the selector is called. The wrapper receives the original selector and the system, and can return a different value or call the original.

```javascript
import { createSelector } from 'reselect'

// FYI: in an actual Swagger UI, the `url` spec selector is already defined
// it's just here for clarity on what's behind the scenes
const MySpecPlugin = function(system) {
  return {
    statePlugins: {
      spec: {
        selectors: {
          url: createSelector(
            state => state.get("url")
          )
        }
      }
    }
  }
}

const MyWrapSelectorsPlugin = function(system) {
  return {
    statePlugins: {
      spec: {
        wrapSelectors: {
          url: (oriSelector, system) => (state, ...args) => {
            console.log('someone asked for the spec url!!! it is', state.get('url'))
            // you can return other values here...
            // but let's just enable the default behavior
            return oriSelector(state, ...args)
          }
        }
      }
    }
  }
}
```

--------------------------------

### Use SwaggerUIBundle from swagger-ui-dist

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/usage/installation.md

For JavaScript projects that can't handle traditional npm modules, use SwaggerUIBundle and SwaggerUIStandalonePreset.

```js
var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle

const ui = SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIBundle.SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  })
```

--------------------------------

### Use Monaco Editor as SyntaxHighlighter in Swagger UI plugin

Source: https://github.com/swagger-api/swagger-ui/wiki/Plugins

Defines a Swagger UI plugin that replaces the default SyntaxHighlighter component with a Monaco Editor instance. It loads Monaco via the @monaco-editor/loader, creates an editor with the provided code and language, and handles cleanup by canceling the loader and disposing the editor. The container height is dynamically calculated based on the number of lines, capped at 450px.

```javascript
import loader from "https://esm.sh/@monaco-editor/loader@1.4.0"

const nojafPlugin = {
  components: {
    SyntaxHighlighter: (props) => {
      const React = props.React;
      const myRef = React.createRef();
      React.useEffect(() => {
        let editor = null;

        const cancelable = loader.init();
        cancelable.then(monaco => {
          if (myRef.current) {
            editor = monaco.editor.create(myRef.current, {
              value: props.children,
              language: props.language
            })
          }
        }).catch(
          (error) =>
            error?.type !== 'cancelation' && console.error('Monaco initialization: error:', error),
        );

        return () => {
          if (cancelable && !myRef.current) {
            cancelable.cancel();
          }

          if (editor) {
            console.log(editor);
            editor.dispose();
          }
        }

      }, [myRef, props.children]);


      // The container needs a height.
      const maxHeight = 450;
      const newLineCount = !props.children ? 0 : (props.children.match(/\n/g)).length
      const proposedHeight = (newLineCount * 14)
      const minHeight = Math.max(100, Math.min(proposedHeight, maxHeight));

      return React.createElement("div", { ref: myRef, style: { minHeight: `${minHeight}px` } }, null);
    }
  }
}
```

--------------------------------

### Calling the action from elsewhere

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/plugin-api.md

Shows how to invoke the defined action using the system reference.

```javascript
// elsewhere
system.exampleActions.updateFavoriteColor("blue")
```

--------------------------------

### Access system via props in a React component

Source: https://github.com/swagger-api/swagger-ui/blob/main/docs/customization/add-plugin.md

Shows how a container component accesses the bound system via props spread from getSystem. Use this pattern to dispatch actions and read selectors from the system in a React component.

```js
class Bobby extends React.Component {

  handleClick(e) {
    this.props.someNamespaceActions.actionName() // fires an action... which the reducer will *eventually* see
  }

  render() {

    let { someNamespaceSelectors, someNamespaceActions } = this.props // this.props has the whole state spread
    let something = someNamespaceSelectors.something() // calls our selector, which returns some state (either an immutable object or value)

    return (
      <h1 onClick={this.handleClick.bind(this)}> Hello {something} </h1> // render the contents
    )

  }

}
```

--------------------------------

### Run security audit

Source: https://github.com/swagger-api/swagger-ui/blob/main/CLAUDE.md

Run a security audit to check for dependency vulnerabilities.

```bash
npm run security-audit     # Run security audit
```
Tokens:
Raw