Swagger UI React

Swagger UI React is a React component wrapper for Swagger UI that enables seamless integration of OpenAPI documentation into React applications. It provides a declarative interface for rendering interactive API documentation with all the features of Swagger UI - including the ability to test API endpoints directly from the documentation.

Package Information

• Package Name: swagger-ui-react
• Package Type: npm
• Language: JavaScript/TypeScript
• Installation: npm install swagger-ui-react

Core Imports

import SwaggerUI from "swagger-ui-react"
import "swagger-ui-react/swagger-ui.css"

For CommonJS:

const SwaggerUI = require("swagger-ui-react")
require("swagger-ui-react/swagger-ui.css")

Basic Usage

import SwaggerUI from "swagger-ui-react"
import "swagger-ui-react/swagger-ui.css"

export default function App() {
  return (
    <SwaggerUI url="https://petstore.swagger.io/v2/swagger.json" />
  )
}

Architecture

Swagger UI React is built around these key components:

• SwaggerUI Component: The main React component that wraps the core Swagger UI functionality
• Props Interface: Comprehensive configuration through React props that map to Swagger UI options
• Static Exports: Access to underlying Swagger UI system components for advanced usage
• Lifecycle Management: React hooks-based lifecycle management with dynamic spec/url updates
• CSS Integration: Separate stylesheet import for UI styling

The component uses React hooks internally and manages the Swagger UI system instance lifecycle, supporting dynamic updates to specs and URLs while maintaining React best practices.

Capabilities

Main Component

The primary SwaggerUI React component for rendering OpenAPI documentation.

function SwaggerUI(props: SwaggerUIProps): JSX.Element | null;

interface SwaggerUIProps {
  // Core content props
  spec?: string | object;
  url?: string;
  
  // Layout and display props
  layout?: string;
  docExpansion?: "list" | "full" | "none";
  defaultModelExpandDepth?: number;
  defaultModelsExpandDepth?: number;
  defaultModelRendering?: "example" | "model";
  displayOperationId?: boolean;
  showExtensions?: boolean;
  showCommonExtensions?: boolean;
  showMutatedRequest?: boolean;
  
  // Interaction props
  supportedSubmitMethods?: Array<"get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace">;
  tryItOutEnabled?: boolean;
  displayRequestDuration?: boolean;
  filter?: string | boolean;
  deepLinking?: boolean;
  
  // Network and security props
  requestInterceptor?: (req: any) => any | Promise<any>;
  responseInterceptor?: (res: any) => any | Promise<any>;
  withCredentials?: boolean;
  oauth2RedirectUrl?: string;
  persistAuthorization?: boolean;
  
  // Request snippets props
  requestSnippetsEnabled?: boolean;
  requestSnippets?: object;
  
  // Plugin system props
  plugins?: Array<object | Function> | Function;
  presets?: Array<Function>;
  queryConfigEnabled?: boolean;
  
  // Lifecycle props
  onComplete?: (system: any) => void;
  initialState?: object;
  uncaughtExceptionHandler?: Function;
}

Usage Examples:

// Basic usage with remote spec URL
<SwaggerUI url="https://petstore.swagger.io/v2/swagger.json" />

// Usage with inline spec object
const openApiSpec = {
  openapi: "3.0.0",
  info: { title: "My API", version: "1.0.0" },
  // ... rest of spec
}
<SwaggerUI spec={openApiSpec} />

// Advanced configuration
<SwaggerUI 
  url="https://api.example.com/openapi.json"
  docExpansion="list"
  defaultModelRendering="model"
  displayOperationId={true}
  tryItOutEnabled={true}
  filter={true}
  requestInterceptor={(req) => {
    req.headers.Authorization = "Bearer " + getAuthToken()
    return req
  }}
  onComplete={(system) => {
    console.log("Swagger UI loaded:", system)
  }}
/>

Static System Access

Direct access to the underlying Swagger UI System class for advanced programmatic usage.

const System: typeof SwaggerUISystem;

Usage Example:

import SwaggerUI from "swagger-ui-react"

// Access the System class for advanced usage
const system = new SwaggerUI.System({
  // system options
})

Preset Collections

Access to Swagger UI preset configurations for customizing the UI behavior.

const presets: {
  base: Function;
  apis: Function;
  [key: string]: Function;
};

Usage Example:

import SwaggerUI from "swagger-ui-react"

// Use presets in advanced configuration
<SwaggerUI
  url="https://api.example.com/openapi.json"
  presets={[SwaggerUI.presets.apis, customPreset]}
/>

Plugin Collections

Access to individual Swagger UI plugins for fine-grained customization.

const plugins: {
  Auth: Function;
  Configs: Function;
  DeepLinking: Function;
  Err: Function;
  Filter: Function;
  Icons: Function;
  JSONSchema5: Function;
  JSONSchema5Samples: Function;
  JSONSchema202012: Function;
  JSONSchema202012Samples: Function;
  Layout: Function;
  Logs: Function;
  OpenAPI30: Function;
  OpenAPI31: Function;
  OnComplete: Function;
  RequestSnippets: Function;
  Spec: Function;
  SwaggerClient: Function;
  Util: Function;
  View: Function;
  ViewLegacy: Function;
  DownloadUrl: Function;
  SyntaxHighlighting: Function;
  Versions: Function;
  SafeRender: Function;
  [key: string]: Function;
};

Usage Example:

import SwaggerUI from "swagger-ui-react"

// Use specific plugins in configuration
<SwaggerUI
  url="https://api.example.com/openapi.json"
  plugins={[SwaggerUI.plugins.Auth, SwaggerUI.plugins.RequestSnippets]}
/>

Configuration Utilities

Access to configuration defaults and utility functions from the underlying Swagger UI system.

const config: {
  defaults: object;
  merge: Function;
  typeCast: Function;
  typeCastMappings: object;
};

Usage Example:

import SwaggerUI from "swagger-ui-react"

// Access default configuration values
const defaultLayout = SwaggerUI.config.defaults.layout
console.log("Default layout:", defaultLayout)

// Use merge utility for complex configurations
const mergedConfig = SwaggerUI.config.merge(
  SwaggerUI.config.defaults,
  { tryItOutEnabled: true, filter: true }
)

Prop Details

Core Content Props

spec - OpenAPI document as JavaScript object, JSON string, or YAML string

• Type: string | object
• Default: undefined
• Note: Don't use with url prop

url - Remote URL to OpenAPI document for fetching and parsing

• Type: string
• Default: undefined
• Note: Don't use with spec prop

Layout Props

layout - Name of top-level layout component via plugin system

• Type: string
• Default: "BaseLayout"
• Note: Applied only on mount

docExpansion - Default expansion setting for operations and tags

• Type: "list" | "full" | "none"
• Default: "list"
• Note: Applied only on mount

defaultModelExpandDepth - Default expansion depth for models

• Type: number
• Default: 1
• Note: Set to -1 to completely hide models; applied only on mount

defaultModelsExpandDepth - Default expansion depth for models section

• Type: number
• Default: 1
• Note: Applied only on mount

defaultModelRendering - Default model rendering mode

• Type: "example" | "model"
• Default: "example"
• Note: Applied only on mount

Interaction Props

tryItOutEnabled - Controls if Try it out section starts enabled

• Type: boolean
• Default: false
• Note: Applied only on mount

supportedSubmitMethods - HTTP methods with Try it out enabled

• Type: Array<"get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace">
• Default: All methods
• Note: Empty array disables Try it out for all operations; applied only on mount

filter - Enables/configures operation filtering

• Type: string | boolean
• Default: false
• Note: Boolean enables/disables, string sets filter expression

Network Props

requestInterceptor - Function to intercept and modify requests

• Type: (req: any) => any | Promise<any>
• Default: undefined
• Parameters: req - Request object to modify
• Returns: Modified request object or Promise resolving to modified request

responseInterceptor - Function to intercept and modify responses

• Type: (res: any) => any | Promise<any>
• Default: undefined
• Parameters: res - Response object to modify
• Returns: Modified response object or Promise resolving to modified response

withCredentials - Enables passing credentials in CORS requests

• Type: boolean
• Default: false
• Note: Applied only on mount

Callback Props

onComplete - Callback triggered when Swagger UI finishes rendering

• Type: (system: any) => void
• Default: undefined
• Parameters: system - Swagger UI system object

Error Handling

Swagger UI React handles errors through:

• uncaughtExceptionHandler prop for custom error handling
• Console logging for rendering errors (when no DOM target specified)
• Built-in error boundaries within Swagger UI system
• Network error handling for remote spec fetching

Limitations

• Not all Swagger UI configuration options are exposed as props
• Most props are applied only on component mount and cannot be updated reliably
• OAuth redirection handling is not supported in React wrapper
• Topbar/Standalone mode is not supported
• React and React DOM are peer dependencies (must be installed separately)

Peer Dependencies

{
  "react": ">=16.8.0 <20",
  "react-dom": ">=16.8.0 <20"
}