Repository: swagger-api/swagger-ui

Stars: 28758

CLAUDE.md

CLAUDE.md - Swagger UI Codebase Guide

Last Updated: 2026-02-24

Version: 5.32.0 (in development)

Purpose: Comprehensive guide for AI assistants working with the Swagger UI codebase

---

1. Repository Overview
2. Project Architecture
3. Development Setup
4. Build System
5. Testing Infrastructure
6. Code Style & Conventions
7. Git Workflow
8. Plugin Architecture
9. Key Files & Directories
10. Common Workflows
11. Important Guidelines

---

Repository Overview

What is Swagger UI?

Swagger UI is a tool that allows developers to visualize and interact with API resources without having implementation logic in place. It's automatically generated from OpenAPI (formerly Swagger) Specification documents.

Multi-Package Monorepo Structure

This repository publishes three different npm packages:

1. swagger-ui (main package)
- Traditional npm module for single-page applications
- Entry: dist/swagger-ui.js
- ES Module: dist/swagger-ui-es-bundle-core.js
- Includes dependency resolution via Webpack/Browserify

2. swagger-ui-dist (distribution package)
- Dependency-free module for server-side projects
- Published separately via GitHub workflow
- Template location: swagger-ui-dist-package/

3. swagger-ui-react (React component)
- React wrapper component
- Location: flavors/swagger-ui-react/
- Uses React hooks
- Released separately via GitHub workflow

OpenAPI Specification Compatibility

- Current Support: OpenAPI 2.0, 3.0.x, 3.1.x
- Latest Version: v5.31.0 (supports up to OpenAPI 3.1.2)

License

Apache 2.0 - See LICENSE and NOTICE files for details.

---

Project Architecture

Technology Stack

Core Framework:
- React 18 (>=16.8.0 <20) - UI components
- Redux 5.0.1 - State management
- Redux Immutable 4.0.0 - Immutable state
- Immutable.js 3.x - Immutable data structures
- React Redux 9.2.0 - React-Redux bindings

API & Schema Processing:
- swagger-client 3.36.0 - OpenAPI client
- js-yaml 4.1.1 - YAML parsing
- remarkable 2.0.1 - Markdown rendering

Security:
- DOMPurify 3.2.6 - HTML sanitization (CRITICAL for XSS prevention)
- serialize-error 8.1.0 - Error serialization

Build Tools:
- Webpack 5.97.1 - Module bundling
- Babel 7.26.x - JavaScript transpilation
- sass-embedded 1.86.0 - SCSS compilation
- PostCSS - CSS processing

Testing:
- Jest 29.7.0 - Unit testing
- Cypress 14.2.0 - E2E testing
- Enzyme 3.11.0 - React component testing

Development:
- ESLint 8.57.0 - JavaScript linting
- Prettier 3.5.3 - Code formatting
- Stylelint 16.19.1 - CSS linting
- Husky 9.1.7 - Git hooks
- lint-staged 15.5.0 - Pre-commit linting

Plugin-Based Architecture

Swagger UI uses a sophisticated plugin system powered by Redux. The core system (src/core/system.js) manages:

- Plugin registration and lifecycle
- Redux store creation and middleware
- State plugin combination
- Action/selector binding
- Configuration management

26 Core Plugins (in src/core/plugins/):
- auth - Authentication handling
- configs - Configuration management
- deep-linking - URL-based navigation
- download-url - Spec downloading
- err - Error handling and transformation
- filter - API filtering
- icons - Icon components
- json-schema-2020-12 - JSON Schema 2020-12 support
- json-schema-2020-12-samples - Sample generation
- json-schema-5 - JSON Schema Draft 5 support
- json-schema-5-samples - Sample generation for Draft 5
- layout - Layout system
- logs - Logging
- oas3 - OpenAPI 3.0.x support
- oas31 - OpenAPI 3.1.x support
- oas32 - OpenAPI 3.2.x support
- on-complete - Completion callbacks
- request-snippets - Code snippet generation
- safe-render - Safe component rendering
- spec - Specification handling
- swagger-client - API client integration
- syntax-highlighting - Code highlighting
- util - Utilities
- versions - Version detection
- view - View rendering
- view-legacy - Legacy view support

---

Development Setup

Prerequisites

- Node.js: >=24.14.0 (Node 24.x recommended, as defined in .nvmrc)
- npm: >=11.9.0
- Git: Any version
- JDK 7+: Required for Nightwatch.js integration tests

Installation Steps

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/

Development Server

The npm run dev command starts a hot-reloading Webpack dev server on port 3200.

Using Local API Definitions

Edit dev-helpers/dev-helper-initializer.js to change the spec URL:

javascript

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

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

Important: Local files must be in the dev-helpers/ directory or subdirectory. Use dev-helpers/examples/ (already in .gitignore).

---

Build System

Babel Environments

Three Babel environments configured in babel.config.js:

1. development/production - Browser builds with modules: "auto"
2. commonjs - CommonJS modules with modules: "commonjs" for Node.js
3. esm - ES modules with modules: false for modern bundlers

Babel Aliases

javascript

{
  root: ".",
  core: "./src/core"
}

Browserslist Environments

Defined in .browserslistrc:

- [browser-production] - Production browser targets
- [browser-development] - Latest Chrome, Firefox, Safari
- [isomorphic-production] - Browser + Node targets
- [node-production] - Maintained Node versions
- [node-development] - Node 24

Build Commands

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

Build Output (dist/)

- swagger-ui.js - Core bundle (CommonJS)
- swagger-ui.css - Compiled styles
- swagger-ui-bundle.js - Isomorphic bundle
- swagger-ui-standalone-preset.js - Standalone preset
- swagger-ui-es-bundle.js - ES module bundle
- swagger-ui-es-bundle-core.js - ES module core
- oauth2-redirect.html - OAuth2 redirect page

Webpack Configurations

Located in webpack/ directory:

- _config-builder.js - Base configuration
- core.js - Core build
- bundle.js - Bundle build
- standalone.js - Standalone build
- es-bundle.js - ES bundle
- es-bundle-core.js - ES core bundle
- stylesheets.js - CSS build
- dev.js - Development server
- dev-e2e.js - E2E testing server

---

Testing Infrastructure

Unit Tests (Jest)

Configuration: config/jest/jest.unit.config.js

Environment: jsdom (simulates browser environment)

Location: test/unit/

Command:

bash

npm run test:unit

Key Features:
- 37 unit test files
- Tests for core plugins, components, system
- XSS security tests
- Silent mode enabled by default (set to false for console output)
- Module name mapper for SVG and standalone imports
- Transform ignore patterns for node_modules exceptions

Setup Files:
- test/unit/jest-shim.js - Polyfills and shims
- test/unit/setup.js - Test environment setup

E2E Tests (Cypress)

Configuration: cypress.config.js

Location: test/e2e-cypress/

Base URL: http://localhost:3230/

Commands:

bash

Run all E2E tests

npm run cy:ci
Interactive Cypress runner

npm run cy:dev
Headless run

npm run cy:run
Start servers and run tests

npm run cy:start     # Starts webpack + mock API

Structure:
- test/e2e-cypress/e2e/ - Test specs (99 test files)
- test/e2e-cypress/static/ - Test fixtures and documents
- test/e2e-cypress/support/ - Test helpers and commands

Test Categories:
- a11y//*cy.js - Accessibility tests
- security//*cy.js - Security tests
- bugs//*cy.js - Bug regression tests
- features//*cy.js - Feature tests

Mock API Server:

bash

npm run cy:mock-api  # JSON Server on port 3204

Artifact Tests

Configuration: config/jest/jest.artifact.config.js

Purpose: Verify build artifacts export correctly

Command:

bash

npm run test:artifact

Complete Test Suite

bash

npm test  # Runs: lint-errors + test:unit + cy:ci

CI/CD Testing

GitHub Actions Workflow: .github/workflows/nodejs.yml

Two Jobs:
1. build - Lint, unit tests, build, artifact tests
2. e2e-tests - Cypress tests (matrix strategy with 3 containers)

Branches: master, next

---

Code Style & Conventions

ESLint Configuration

File: .eslintrc.js

Parser: @babel/eslint-parser

Key Rules:
- semi: [2, "never"] - No semicolons
- quotes: [2, "double"] - Double quotes (allow template literals)
- no-unused-vars: 2 - Error on unused variables
- camelcase: ["error"] - Enforce camelCase (with exceptions for UNSAFE_, request generators, etc.)
- no-console: [2, {allow: ["warn", "error"]}] - Only console.warn and console.error allowed
- react/jsx-no-bind: 1 - Warning for JSX bind
- react/jsx-filename-extension: 2 - JSX only in .jsx files
- import/no-extraneous-dependencies: 2 - Error on extraneous dependencies

Extends:
- eslint:recommended
- plugin:react/recommended
- plugin:prettier/recommended

Prettier Configuration

File: .prettierrc.yaml

Settings:

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

IMPORTANT: Prettier requires @prettier pragma comment at the top of files:

javascript

/
 * @prettier
 */

Stylelint Configuration

File: stylelint.config.js

Custom Syntax: postcss-scss

Rules:
- Uses stylelint-prettier plugin
- Prettier integration without pragma requirement

Pre-commit Hooks

Husky: .husky/pre-commit runs npx lint-staged

Lint-staged Configuration: .lintstagedrc

json

{
  "*.{js,jsx}": ["eslint --max-warnings 0"],
  ".scss": ["stylelint '/.scss'"]
}

Critical: All staged JS/JSX/SCSS files are linted with zero warnings tolerance.

File Structure Conventions

Components:
- Location: src/core/components/
- Extension: .jsx (React components)
- Format: PascalCase for component names

Styles:
- Location: src/style/
- Extension: .scss
- Format: SCSS with PostCSS processing
- Dark mode: _dark-mode.scss

Tests:
- Unit: test/unit/ (mirrors source structure)
- E2E: test/e2e-cypress/e2e/
- Naming: .test.js, .spec.js, *.cy.js (Cypress)

---

Git Workflow

Branch Strategy

Main Branches:
- master - Production releases
- next - Next version development

Feature Branches:
- Should branch from master or next
- Use descriptive names

Commit Conventions

Format: Conventional Commits (enforced by commitlint)

Structure:

text

<type>(<scope>): <subject>
<body><footer>

Types:
- feat - New feature
- fix - Bug fix
- docs - Documentation changes
- style - Code style changes (formatting)
- refactor - Code refactoring
- test - Test additions/changes
- chore - Build/tooling changes
- perf - Performance improvements

Example:

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

Pull Request Process

Template: .github/pull_request_template.md

Required Sections:
1. Description - Detailed change description
2. Motivation and Context - Why the change is needed
3. How Has This Been Tested? - Manual testing details
4. Screenshots - If UI changes

Checklist:
- [ ] Code type (no code/dependencies/bug fix/improvement/feature)
- [ ] Breaking changes identification
- [ ] Documentation updates
- [ ] Test coverage
- [ ] All tests passing

CI Checks:
- ESLint (error-only mode)
- Unit tests (Jest)
- Build verification
- Artifact tests
- E2E tests (Cypress)

Release Process

Tool: release-it with conventional-changelog

Command:

bash

npm run automated-release

Workflows:
- .github/workflows/release-swagger-ui.yml
- .github/workflows/release-swagger-ui-dist.yml
- .github/workflows/release-swagger-ui-react.yml
- .github/workflows/release-swagger-ui-packagist.yml

---

Plugin Architecture

Core System (`src/core/system.js`)

The plugin system is the heart of Swagger UI. It uses Redux for state management with a custom plugin registration system.

Plugin Structure

Each plugin is a JavaScript object/function that returns:

javascript

{
  statePlugins: {
    [pluginName]: {
      actions: {},      // Redux actions
      reducers: {},     // Redux reducers
      selectors: {},    // Reselect selectors
      wrapActions: {},  // Action middleware
      wrapSelectors: {} // Selector middleware
    }
  },
  components: {},       // React components
  fn: {},              // Utility functions
  rootInjects: {},     // Root-level injections
  afterLoad: Function  // Lifecycle hook
}

Key Plugin Locations

Core Plugins: src/core/plugins/

Each plugin has:
- index.js - Main export
- actions.js - Redux actions
- reducers.js - Redux reducers
- selectors.js - State selectors
- wrap-actions.js - Action middleware
- wrap-selectors.js - Selector middleware
- Component files (.jsx)

Creating a Plugin

See documentation: docs/customization/plugin-api.md

Cross-Plugin Import Guidelines

IMPORTANT: Avoid cross-plugin imports to maintain plugin independence and modularity.

Pattern to Follow:
- Each plugin should be self-contained with its own components, utilities, and functions
- When OAS version plugins (oas3, oas31, oas32) need similar functionality, create self-contained copies within each plugin
- Wrap components should import from their own plugin's components, not from other plugins

Example Structure:

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

Why This Matters:
- Prevents tight coupling between plugins
- Makes plugins easier to test in isolation
- Allows independent versioning and updates
- Reduces risk of breaking changes across plugins
- Improves code maintainability

Exceptions:
- Shared core utilities in src/core/utils/ are acceptable
- System-level functions in src/core/system.js are acceptable
- Base components in src/core/components/ are acceptable

Preset System

Base Preset: src/core/presets/base.js

Standalone Preset: src/standalone/presets/standalone.js

Presets are collections of plugins bundled together for specific use cases.

---

Key Files & Directories

Critical Source Files

text

src/
├── core/
│   ├── system.js                 # Plugin system & Redux store
│   ├── components/               # 59 React components
│   ├── plugins/                  # 26 core plugins
│   ├── presets/                  # Preset configurations
│   ├── utils/                    # Utility functions
│   └── config/                   # Configuration system
├── standalone/
│   ├── plugins/                  # TopBar, StandaloneLayout
│   └── presets/                  # Standalone preset
├── style/                        # SCSS stylesheets
│   ├── _dark-mode.scss          # Dark mode styles
│   └── main.scss                # Main stylesheet entry
└── index.js                      # Main package entry

Configuration Files

text

.
├── package.json                  # Dependencies & scripts
├── babel.config.js              # Babel configuration
├── .eslintrc.js                 # ESLint rules
├── .prettierrc.yaml             # Prettier settings
├── stylelint.config.js          # Stylelint rules
├── .browserslistrc              # Browser targets
├── .nvmrc                       # Node version (24.x)
├── .lintstagedrc                # Pre-commit linting
└── cypress.config.js            # Cypress E2E config

Build & Tooling

text

webpack/ ├── _config-builder.js # Base Webpack config ├── core.js # Core build ├── bundle.js # Bundle build ├── standalone.js # Standalone build ├── es-bundle.js # ES bundle build ├── es-bundle-core.js # ES core bundle ├── stylesheets.js # CSS compilation ├── dev.js # Dev server └── dev-e2e.js # E2E dev server

config/jest/ ├── jest.unit.config.js # Unit test config └── jest.artifact.config.js # Artifact test config

Documentation

text

docs/
├── usage/
│   ├── installation.md
│   ├── configuration.md
│   ├── cors.md
│   ├── oauth2.md
│   ├── deep-linking.md
│   ├── version-detection.md
│   └── limitations.md
├── customization/
│   ├── overview.md
│   ├── plugin-api.md
│   └── custom-layout.md
└── development/
    ├── setting-up.md
    └── scripts.md

Testing

text

test/
├── unit/                        # Jest unit tests (37 files)
│   ├── setup.js                # Test environment setup
│   └── jest-shim.js           # Polyfills
├── e2e-cypress/                 # Cypress E2E tests (99 files)
│   ├── e2e/                    # Test specs
│   ├── static/                 # Fixtures
│   └── support/                # Helpers
└── e2e-selenium/               # Legacy Selenium tests

Distribution

text

flavors/ └── swagger-ui-react/ # React component wrapper swagger-ui-dist-package/ # Template for dist package

dist/ # Build output (generated) ├── swagger-ui.js ├── swagger-ui.css ├── swagger-ui-bundle.js ├── swagger-ui-standalone-preset.js ├── swagger-ui-es-bundle.js ├── swagger-ui-es-bundle-core.js └── oauth2-redirect.html

---

Common Workflows

Making Code Changes

1. Read before modifying:

bash

# ALWAYS read files before editing them
   # Understand the existing code structure

2. Follow the style guide:
- Use double quotes
- No semicolons
- Add @prettier pragma to new files
- Use .jsx extension for React components

3. Run linters:

bash

npm run lint          # Check for errors and warnings
   npm run lint-fix      # Auto-fix JavaScript issues
   npm run lint-styles   # Check SCSS
   npm run lint-styles-fix  # Auto-fix SCSS

4. Test your changes:

bash

npm run test:unit     # Run unit tests
   npm run cy:dev        # Interactive E2E testing
   npm run build         # Verify build works
   npm run test:artifact # Verify artifacts

Adding a New Component

1. Create component in src/core/components/ or appropriate plugin directory
2. Use .jsx extension
3. Add @prettier pragma
4. Follow React best practices (functional components, hooks)
5. Add PropTypes validation
6. Create corresponding test in test/unit/
7. Export from plugin's index.js if needed

Adding a New Plugin

1. Create directory in src/core/plugins/[plugin-name]/
2. Create index.js with plugin structure
3. Add actions, reducers, selectors as needed
4. Register plugin in preset (e.g., src/core/presets/base.js)
5. Add tests in test/unit/core/plugins/[plugin-name]/
6. Document the plugin

Fixing a Bug

1. Reproduce the bug:
- Add a failing test in test/unit/ or test/e2e-cypress/
- Document reproduction steps

2. Fix the issue:
- Make minimal changes to fix the bug
- Avoid refactoring unless necessary
- Ensure the test now passes

3. Verify:

bash

npm run test:unit
   npm run build
   npm run test:artifact

4. Create PR:
- Reference the issue number
- Include before/after behavior
- Add screenshots if UI-related

Adding a Feature

1. Plan the feature:
- Review existing architecture
- Identify affected plugins/components
- Consider OpenAPI spec compatibility

2. Implement:
- Follow plugin architecture patterns
- Add configuration options if needed
- Update presets if necessary

3. Test thoroughly:
- Unit tests for logic
- Component tests for UI
- E2E tests for integration
- Test with various OpenAPI specs

4. Document:
- Update docs/ if user-facing
- Add JSDoc comments for APIs
- Update README if needed

Security Considerations

1. XSS Prevention:
- ALWAYS use DOMPurify for user-provided HTML
- Sanitize all external input
- Review test/unit/xss/ for examples
- Never use dangerouslySetInnerHTML without sanitization

2. Input Validation:
- Validate API responses
- Handle malformed OpenAPI specs gracefully
- Check for prototype pollution

3. Dependency Security:

bash

npm run security-audit     # Run security audit

Working with OpenAPI Specs

Testing Different Versions:
- OAS 2.0: Use src/core/plugins/swagger-client/
- OAS 3.0.x: Use src/core/plugins/oas3/
- OAS 3.1.x: Use src/core/plugins/oas31/
- OAS 3.2.x: Use src/core/plugins/oas32/

Adding Test Specs:
- Add to test/e2e-cypress/static/documents/
- Reference in E2E tests

---

Important Guidelines

DO's ✅

1. Always read files before modifying them
2. Follow the no-semicolon convention
3. Use double quotes for strings
4. Add @prettier pragma to all new files
5. Use .jsx extension for React components
6. Write tests for new features and bug fixes
7. Run linters before committing (automatic via husky)
8. Use DOMPurify for HTML sanitization
9. Follow conventional commit format
10. Update documentation for user-facing changes
11. Test with multiple OpenAPI spec versions
12. Check browser compatibility (see .browserslistrc)
13. Use the plugin architecture - don't modify core unnecessarily
14. Preserve backward compatibility unless explicitly breaking
15. Run full test suite before submitting PR
16. Keep plugins self-contained - avoid cross-plugin imports (see Cross-Plugin Import Guidelines)

DON'Ts ❌

1. Don't use semicolons - project convention
2. Don't use single quotes - use double quotes
3. Don't skip the @prettier pragma - required for formatting
4. Don't put React in .js files - use .jsx
5. Don't commit files in dev-helpers/ (except core files)
6. Don't commit build artifacts (dist/ is gitignored)
7. Don't skip tests - they run in CI
8. Don't bypass ESLint - pre-commit hook enforces
9. Don't use console.log - only console.warn and console.error
10. Don't render unsanitized HTML - XSS vulnerability
11. Don't modify package-lock.json manually
12. Don't push directly to master or next
13. Don't ignore Cypress test failures
14. Don't add dependencies without justification
15. Don't break the build - verify with npm run build
16. Don't import from other plugins - create self-contained copies instead (e.g., don't import from oas31 in oas32)

When Working with AI Assistants

Before Making Changes:
1. Read the affected files completely
2. Understand the plugin architecture
3. Check for existing tests
4. Review related documentation

During Development:
1. Make minimal, focused changes
2. Follow existing patterns in the codebase
3. Add tests alongside code changes
4. Run linters frequently

After Changes:
1. Verify all tests pass
2. Check build completes successfully
3. Test artifact exports
4. Review for security issues
5. Update relevant documentation

Communication:
- Be explicit about file locations
- Use line number references (e.g., src/core/system.js:96)
- Provide context for changes
- Mention any breaking changes clearly

Performance Considerations

1. Immutable.js:
- Use Immutable data structures for state
- Use .toJS() sparingly (expensive)
- Prefer Immutable operations

2. React:
- Use React.memo for pure components
- Implement shouldComponentUpdate for class components
- Avoid inline function definitions in render

3. Redux:
- Use reselect for memoized selectors
- Keep reducers pure and fast
- Avoid large state trees

4. Bundle Size:
- Check bundle size with npm run deps-size
- Review dependency licenses with npm run deps-license
- Consider code splitting for large features

Debugging Tips

Development Server:

bash

npm run dev
Open http://localhost:3200/

Hot reload enabled

Unminified stack traces

Redux DevTools:
- Extension supported
- State inspection available
- Time-travel debugging

Cypress Interactive Mode:

bash

npm run cy:dev
Visual test runner

Step-through debugging

Network inspection

Jest Watch Mode:

bash

npm run test:unit -- --watch
Re-run on file changes

Filter by file name or test name

Source Maps:
- Generated for all builds
- Enable in browser DevTools
- Original source debugging

---

Quick Reference

Essential Commands

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 cy:dev           # Cypress interactive
npm run cy:ci            # Cypress CI mode
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

File Paths

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-cypress/e2e/
Build Output:          dist/

Port Reference

- 3200 - Development server (webpack-dev-server)
- 3002 - Static file server (local-web-server)
- 3204 - Mock API server (json-server)
- 3230 - E2E test server (webpack-dev-server)

---

Additional Resources

Documentation

- Setup Guide: docs/development/setting-up.md
- Scripts Reference: docs/development/scripts.md
- Plugin API: docs/customization/plugin-api.md
- Configuration: docs/usage/configuration.md
- OAuth2 Setup: docs/usage/oauth2.md

External Links

- Homepage: https://swagger.io/tools/swagger-ui/
- Repository: https://github.com/swagger-api/swagger-ui
- npm (main): https://www.npmjs.com/package/swagger-ui
- npm (dist): https://www.npmjs.com/package/swagger-ui-dist
- npm (react): https://www.npmjs.com/package/swagger-ui-react
- OpenAPI Spec: https://spec.openapis.org/

Community

- Issues: https://github.com/swagger-api/swagger-ui/issues
- Good First Issues: https://github.com/swagger-api/swagger-ui/issues?q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%22
- Security: [email protected]
- Contributing: https://github.com/swagger-api/.github/blob/HEAD/CONTRIBUTING.md

---

Note: This document should be updated whenever major architectural changes, new conventions, or significant workflows are introduced to the codebase.

README.md

<img src="https://raw.githubusercontent.com/swagger-api/swagger.io/wordpress/images/assets/SWU-logo-clr.png" width="300">

![NPM version](http://badge.fury.io/js/swagger-ui)
![Build Status](https://jenkins.swagger.io/view/OSS%20-%20JavaScript/job/oss-swagger-ui-master/)
![npm audit](https://jenkins.swagger.io/job/oss-swagger-ui-security-audit/lastBuild/console)
![total GitHub contributors](https://github.com/swagger-api/swagger-ui/graphs/contributors)

![monthly npm installs](https://www.npmjs.com/package/swagger-ui)
!docker registry
!monthly packagist installs
![gzip size](https://bundlephobia.com/package/swagger-ui)

Introduction

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

General

👉🏼 Want to score an easy open-source contribution? Check out our Good first issue label.

🕰️ Looking for the older version of Swagger UI? Refer to the 2.x branch.

This repository publishes three different NPM modules:

* swagger-ui is a traditional npm module intended for use in single-page applications that are capable of resolving dependencies (via Webpack, Browserify, etc.).
* swagger-ui-dist is a dependency-free module that includes everything you need to serve Swagger UI in a server-side project, or a single-page application that can't resolve npm module dependencies.
* swagger-ui-react is Swagger UI packaged as a React component for use in React applications.

We strongly suggest that you use swagger-ui instead of swagger-ui-dist if you're building a single-page application, since swagger-ui-dist is significantly larger.

If you are looking for plain ol' HTML/JS/CSS, download the latest release and copy the contents of the /dist folder to your server.

Compatibility

The OpenAPI Specification has undergone 5 revisions since initial creation in 2010. Compatibility between Swagger UI and the OpenAPI Specification is as follows:

| Swagger UI Version | Release Date | OpenAPI Spec compatibility | Notes |
|--------------------|--------------|-------------------------------------------------------------|-----------------------------------------------------------------------|
| 5.32.0 | 2026-02-27 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0 | tag v5.32.0 |
| 5.19.0 | 2025-02-17 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2 | tag v5.19.0 |
| 5.0.0 | 2023-06-12 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0 | tag v5.0.0 |
| 4.0.0 | 2021-11-03 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3 | tag v4.0.0 |
| 3.18.3 | 2018-08-03 | 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3 | tag v3.18.3 |
| 3.0.21 | 2017-07-26 | 2.0 | tag v3.0.21 |
| 2.2.10 | 2017-01-04 | 1.1, 1.2, 2.0 | tag v2.2.10 |
| 2.1.5 | 2016-07-20 | 1.1, 1.2, 2.0 | tag v2.1.5 |
| 2.0.24 | 2014-09-12 | 1.1, 1.2 | tag v2.0.24 |
| 1.0.13 | 2013-03-08 | 1.1, 1.2 | tag v1.0.13 |
| 1.0.1 | 2011-10-11 | 1.0, 1.1 | tag v1.0.1 |

Anonymized analytics

SwaggerUI 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:

text

// 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.

Documentation

#### Usage
- Installation
- Configuration
- CORS
- OAuth2
- Deep Linking
- Limitations
- Version detection

#### Customization
- Overview
- Plugin API
- Custom layout

#### Development
- Setting up
- Scripts

#### Contributing
- Contributing

##### Integration Tests

You will need JDK of version 7 or higher as instructed here
https://nightwatchjs.org/guide/getting-started/installation.html#install-selenium-server

Integration tests can be run locally with npm run e2e - be sure you aren't running a dev server when testing!

Browser support

Swagger UI works in the latest versions of Chrome, Safari, Firefox, and Edge.

Known Issues

To help with the migration, here are the currently known issues with 3.X. This list will update regularly, and will not include features that were not implemented in previous versions.

- Only part of the parameters previously supported are available.
- The JSON Form Editor is not implemented.
- Support for collectionFormat is partial.
- l10n (translations) is not implemented.
- Relative path support for external files is not implemented.

Security contact

Please disclose any security-related issues or vulnerabilities by emailing [email protected], instead of using the public issue tracker.

License

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

Repository: swagger-api/swagger-ui

Stars: 28758

CLAUDE.md Copy Chapter

CLAUDE.md - Swagger UI Codebase Guide

Table of Contents Copy Chapter

Repository Overview Copy Chapter

What is Swagger UI? Copy Section

Multi-Package Monorepo Structure Copy Section

OpenAPI Specification Compatibility Copy Section

License Copy Section

Project Architecture Copy Chapter

Technology Stack Copy Section

Plugin-Based Architecture Copy Section

Development Setup Copy Chapter

Prerequisites Copy Section

Installation Steps Copy Section

Clone the repository

Install dependencies

Initialize Husky (optional, for git hooks)

Start development server

Open http://localhost:3200/

Development Server Copy Section

Using Local API Definitions Copy Section

Build System Copy Chapter

Babel Environments Copy Section

Babel Aliases Copy Section

Browserslist Environments Copy Section

Build Commands Copy Section

Full build (stylesheets + all bundles)

Individual builds

Clean build artifacts

Build Output (dist/) Copy Section

Webpack Configurations Copy Section

Testing Infrastructure Copy Chapter

Unit Tests (Jest) Copy Section

E2E Tests (Cypress) Copy Section

Run all E2E tests

Interactive Cypress runner

Headless run

Start servers and run tests

Artifact Tests Copy Section

Complete Test Suite Copy Section

CI/CD Testing Copy Section

Code Style & Conventions Copy Chapter

ESLint Configuration Copy Section

Prettier Configuration Copy Section

Stylelint Configuration Copy Section

Pre-commit Hooks Copy Section

File Structure Conventions Copy Section

Git Workflow Copy Chapter

Branch Strategy Copy Section

Commit Conventions Copy Section

Pull Request Process Copy Section

Release Process Copy Section

Plugin Architecture Copy Chapter

Core System (src/core/system.js) src/core/system.js)')" title="Copy section prompt for LLMs"> Copy Section

Plugin Structure Copy Section

Key Plugin Locations Copy Section

Creating a Plugin Copy Section

Cross-Plugin Import Guidelines Copy Section

Preset System Copy Section

Key Files & Directories Copy Chapter

Critical Source Files Copy Section

Configuration Files Copy Section

Build & Tooling Copy Section

Documentation Copy Section

Testing Copy Section

Distribution Copy Section

Common Workflows Copy Chapter

Making Code Changes Copy Section

Adding a New Component Copy Section

Adding a New Plugin Copy Section

Fixing a Bug Copy Section

Adding a Feature Copy Section

Security Considerations Copy Section

Working with OpenAPI Specs Copy Section

Important Guidelines Copy Chapter

DO's ✅ Copy Section

DON'Ts ❌ Copy Section

When Working with AI Assistants Copy Section

CLAUDE.md

Table of Contents

Repository Overview

What is Swagger UI?

Multi-Package Monorepo Structure

OpenAPI Specification Compatibility

License

Project Architecture

Technology Stack

Plugin-Based Architecture

Development Setup

Prerequisites

Installation Steps

Development Server

Using Local API Definitions

Build System

Babel Environments

Babel Aliases

Browserslist Environments

Build Commands

Build Output (dist/)

Webpack Configurations

Testing Infrastructure

Unit Tests (Jest)

E2E Tests (Cypress)

Artifact Tests

Complete Test Suite

CI/CD Testing

Code Style & Conventions

ESLint Configuration

Prettier Configuration

Stylelint Configuration

Pre-commit Hooks

File Structure Conventions

Git Workflow

Branch Strategy

Commit Conventions

Pull Request Process

Release Process

Plugin Architecture

Core System (`src/core/system.js`)

Plugin Structure

Key Plugin Locations

Creating a Plugin

Cross-Plugin Import Guidelines

Preset System

Key Files & Directories

Critical Source Files

Configuration Files

Build & Tooling

Documentation

Testing

Distribution

Common Workflows

Making Code Changes

Adding a New Component

Adding a New Plugin

Fixing a Bug

Adding a Feature

Security Considerations

Working with OpenAPI Specs

Important Guidelines

DO's ✅

DON'Ts ❌

When Working with AI Assistants

Performance Considerations

Debugging Tips

Quick Reference

Essential Commands

File Paths

Port Reference

Additional Resources

Documentation

External Links

Community

README.md

Introduction

General

Compatibility

Anonymized analytics