From b8a3c4bfef13c0da0890d24e45d8c49abc016485 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Jan 2026 16:18:21 +0000 Subject: [PATCH] docs: add comprehensive CLAUDE.md guide for AI assistants Add detailed documentation for AI assistants working with the Swagger UI codebase, including: - Repository overview and multi-package structure - Complete technology stack and dependencies - Plugin-based architecture explanation - Development setup and prerequisites - Build system with Babel/Webpack configurations - Testing infrastructure (Jest, Cypress, Enzyme) - Code style conventions (ESLint, Prettier, Stylelint) - Git workflow and conventional commit guidelines - Key files and directories reference - Common workflows for development tasks - Security best practices - Performance considerations - Quick reference for essential commands This guide helps AI assistants understand the codebase structure, follow project conventions, and make appropriate changes while maintaining code quality and consistency. --- CLAUDE.md | 1032 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1032 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000000..bbd932ce843 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,1032 @@ +# CLAUDE.md - Swagger UI Codebase Guide + +> **Last Updated:** 2026-01-21 +> **Version:** 5.31.0 +> **Purpose:** Comprehensive guide for AI assistants working with the Swagger UI codebase + +--- + +## Table of Contents + +1. [Repository Overview](#repository-overview) +2. [Project Architecture](#project-architecture) +3. [Development Setup](#development-setup) +4. [Build System](#build-system) +5. [Testing Infrastructure](#testing-infrastructure) +6. [Code Style & Conventions](#code-style--conventions) +7. [Git Workflow](#git-workflow) +8. [Plugin Architecture](#plugin-architecture) +9. [Key Files & Directories](#key-files--directories) +10. [Common Workflows](#common-workflows) +11. [Important Guidelines](#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.1) + +### 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 +- `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:** >=22.11.0 (Node 20.x recommended, as defined in `.nvmrc`) +- **npm:** >=10.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 22 + +### 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:** +``` +(): + + + +