Swagger UI for React

Common errors

• Module not found: Error: Can't resolve 'swagger-ui-react/swagger-ui.css'

  cause The CSS file for Swagger UI styling is not imported or the import path is incorrect.
  fix Add `import "swagger-ui-react/swagger-ui.css";` to your component or main application file to ensure styles are loaded.

• Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

  cause The `SwaggerUI` component was likely imported incorrectly, often as a CommonJS `require()` or as a named import when it's a default export.
  fix Ensure you are using `import SwaggerUI from "swagger-ui-react";` for the default export.

• npm ERR! ERESOLVE unable to resolve dependency tree ... peer react@"..." from swagger-ui-react@...

  cause `react` or `react-dom` peer dependencies are not met or are not installed in your project.
  fix Install `react` and `react-dom` in your project with versions compatible with `swagger-ui-react` (e.g., `npm install react react-dom`). The current peer dependency range is `>=16.8.0 <20`.

• Warning: Cannot update a component (`SwaggerUI`) while rendering a different component (`App`).

  cause Attempting to update a Swagger UI prop (e.g., `url` or `spec`) based on state changes within the same render cycle can lead to React warnings.
  fix Ensure that props passed to `SwaggerUI` are stable during a render. If `url` or `spec` need to change, ensure the change is triggered by a user interaction or a state update outside of the direct render function flow, or consider using `React.memo` or `useMemo` for complex prop values.

Warnings

• breaking Major versions of `swagger-ui-react` correspond to `swagger-ui` releases. Upgrading major versions may introduce breaking changes in API behavior, configuration options, or UI rendering. Always review the `swagger-ui` changelog when updating major versions.
  Fix: Consult the official Swagger UI release notes for breaking changes before upgrading. Test thoroughly in a staging environment.
• gotcha The `spec` and `url` props are mutually exclusive. Providing both can lead to unpredictable behavior in how the OpenAPI document is loaded and displayed.
  Fix: Always use either `spec` (for inline JSON/YAML) OR `url` (for remote fetching), but never both simultaneously.
• gotcha Certain props, such as `layout` and `docExpansion`, are currently only applied once on initial mount of the component. Subsequent changes to these props will not cause the underlying Swagger UI instance to update.
  Fix: If dynamic changes to these specific props are required, consider remounting the `SwaggerUI` component (e.g., by changing its `key` prop) or explore using the Swagger UI system object obtained via `onComplete` for programmatic control.
• gotcha This package uses Scarf for anonymized installation analytics. This only occurs during `npm install` and helps support maintainers.
  Fix: To opt out, set `"scarfSettings": { "enabled": false }` in your `package.json` or set the environment variable `SCARF_ANALYTICS=false` during installation.
• breaking Recent versions (e.g., v5.32.4, v5.32.2) include fixes for high-severity CVEs in underlying Docker images and dependencies like `libpng` and `zlib`. While these are primarily for Docker users, dependency updates in patch releases can sometimes introduce subtle behavioral changes.
  Fix: Ensure you are on the latest patch release to benefit from security updates. Review the changelog for specific dependency bumps.

Install

• npm install swagger-ui-react npm
• yarn add swagger-ui-react yarn
• pnpm add swagger-ui-react pnpm

Imports

• SwaggerUI
  wrong:

  const SwaggerUI = require("swagger-ui-react");

  correct:

  import SwaggerUI from "swagger-ui-react";

  Primary component for rendering Swagger UI. This is an ESM default export.
• CSS
  wrong:

  import "swagger-ui-react/dist/swagger-ui.css";

  correct:

  import "swagger-ui-react/swagger-ui.css";

  Required to style the Swagger UI component. The correct path is directly under the package root.
• Props (TypeScript)

  import type { SwaggerUIProps } from "swagger-ui-react";

  Use `import type` for type-only imports in TypeScript environments.

Quickstart

This quickstart demonstrates how to integrate `SwaggerUI` into a React component, loading an OpenAPI specification from a URL, applying initial documentation expansion settings, and including basic interceptor and completion callbacks. It also shows a common pattern for defining the API URL via environment variables.

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

const App = () => {
  const apiUrl = process.env.REACT_APP_SWAGGER_URL || "https://petstore.swagger.io/v2/swagger.json";
  const initialDocExpansion = "list"; // 'list', 'full', 'none'

  return (
    <div style={{ padding: '20px' }}>
      <h1>My API Documentation</h1>
      <SwaggerUI 
        url={apiUrl} 
        docExpansion={initialDocExpansion}
        requestInterceptor={(req) => {
          // Example: Add an authorization header
          // req.headers.Authorization = `Bearer ${someAuthToken}`;
          return req;
        }}
        onComplete={(system) => {
          console.log("Swagger UI finished rendering.", system);
        }}
      />
    </div>
  );
};

export default App;