swagger-ui-react

What is swagger-ui-react?

The swagger-ui-react npm package is a React component for integrating the Swagger UI into a React application. Swagger UI allows developers to visualize and interact with the API's resources without having any of the implementation logic in place. It is particularly useful for API documentation and testing.

What are swagger-ui-react's main functionalities?

Basic Integration

This code demonstrates how to integrate Swagger UI into a React application using the swagger-ui-react package. It imports the necessary components and styles, and then renders the Swagger UI with a given URL to the Swagger JSON.

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

const App = () => (
  <SwaggerUI url="https://petstore.swagger.io/v2/swagger.json" />
);

export default App;

Custom Configuration

This code sample shows how to customize the Swagger UI component by passing additional props. In this example, the `docExpansion` prop is set to 'none' to collapse all sections by default, and `defaultModelsExpandDepth` is set to -1 to hide the models section.

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

const App = () => (
  <SwaggerUI 
    url="https://petstore.swagger.io/v2/swagger.json"
    docExpansion="none"
    defaultModelsExpandDepth={-1}
  />
);

export default App;

Using Local Swagger JSON

This example demonstrates how to use a local Swagger JSON file with the Swagger UI component. The local Swagger JSON file is imported and passed to the `spec` prop of the SwaggerUI component.

import React from 'react';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';
import swaggerDocument from './swagger.json';

const App = () => (
  <SwaggerUI spec={swaggerDocument} />
);

export default App;

Other packages similar to swagger-ui-react

redoc

Redoc is another popular tool for API documentation. It provides a more modern and responsive UI compared to Swagger UI. Redoc is known for its clean and customizable interface, and it supports OpenAPI 3.0. It is often preferred for its aesthetics and ease of use.

swagger-jsdoc

Swagger-jsdoc is a tool that allows you to integrate JSDoc comments in your codebase to generate Swagger documentation. It is useful for those who prefer to keep their API documentation close to their code. Unlike swagger-ui-react, it focuses on generating the Swagger JSON rather than rendering it.

api-docs

API Docs is a lightweight alternative for generating API documentation. It is less feature-rich compared to Swagger UI but can be a good choice for smaller projects or those who need a simple and quick way to document their APIs.

README

swagger-ui-react

swagger-ui-react is a flavor of Swagger UI suitable for use in React applications.

It has a few differences from the main version of Swagger UI:

• Declares react and react-dom as peerDependencies instead of production dependencies
• Exports a component instead of a constructor function

Versions of this module mirror the version of Swagger UI included in the distribution.

Anonymized analytics

swagger-ui-react 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:

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

Quick start

Install swagger-ui-react:

$ npm i --save swagger-ui-react

Use it in your React application:

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

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

Props

These props map to Swagger UI configuration options of the same name.

spec: PropTypes.object

An OpenAPI document represented as a JavaScript object, JSON string, or YAML string for Swagger UI to display.

⚠️ Don't use this in conjunction with url - unpredictable behavior may occur.

url: PropTypes.string

Remote URL to an OpenAPI document that Swagger UI will fetch, parse, and display.

⚠️ Don't use this in conjunction with spec - unpredictable behavior may occur.

layout: PropTypes.string

The name of a component available via the plugin system to use as the top-level layout for Swagger UI. The default value is BaseLayout.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

onComplete: PropTypes.func

(system) => void

A callback function that is triggered when Swagger-UI finishes rendering an OpenAPI document.

Swagger UI's system object is passed as an argument.

requestInterceptor: PropTypes.func

req => req or req => Promise<req>.

A function that accepts a request object, and returns either a request object or a Promise that resolves to a request object.

responseInterceptor: PropTypes.func

res => res or res => Promise<res>.

A function that accepts a response object, and returns either a response object or a Promise that resolves to a response object.

docExpansion: PropTypes.oneOf(['list', 'full', 'none'])

Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing). The default value is 'list'.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

defaultModelExpandDepth: PropTypes.number

The default expansion depth for models (set to -1 completely hide the models).

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

defaultModelRendering: PropTypes.oneOf(["example", "model"])

Controls how the model is shown when the API is first rendered. (The user can always switch the rendering for a given model by clicking the 'Model' and 'Example Value' links.) The default value is 'example'.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

displayOperationId: PropTypes.bool

Controls the display of operationId in operations list. The default is false.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

plugins: PropTypes.arrayOf(PropTypes.object),

An array of objects that augment and modify Swagger UI's functionality. See Swagger UI's Plugin API for more details.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

supportedSubmitMethods: PropTypes.arrayOf(PropTypes.oneOf(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']))

HTTP methods that have the Try it out feature enabled. An empty array disables Try it out for all operations. This does not filter the operations from the display.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

showExtensions: PropTypes.bool

Controls the display of vendor extension (x-) fields and values for Operations, Parameters, Responses, and Schema.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

showCommonExtensions: PropTypes.bool

Controls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields and values for Parameters.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

showMutatedRequest: PropTypes.bool

If set to true, uses the mutated request returned from a requestInterceptor to produce the curl command in the UI, otherwise the request before the requestInterceptor was applied is used.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

presets: PropTypes.arrayOf(PropTypes.func),

An array of functions that augment and modify Swagger UI's functionality. See Swagger UI's Plugin API for more details.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

tryItOutEnabled: PropTypes.bool

Controls whether the "Try it out" section should start enabled. The default is false.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

displayRequestDuration: PropTypes.bool

Controls the display of the request duration (in milliseconds) for "Try it out" requests. The default is false.

filter: PropTypes.oneOfType([PropTypes.string, PropTypes.bool])

If set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown. Can be Boolean to enable or disable, or a string, in which case filtering will be enabled using that string as the filter expression. Filtering is case sensitive matching the filter expression anywhere inside the tag. See Swagger UI's Plug Points to customize the filtering behavior.

requestSnippetsEnabled: PropTypes.bool,

Enables the request snippet section. When disabled, the legacy curl snippet will be used. The default is false.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

requestSnippets: PropTypes.object,

Configures the request snippet core plugin. See Swagger UI's Display Configuration for more details.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

persistAuthorization: PropTypes.bool

If set, it persists authorization data and it would not be lost on browser close/refresh. The default is false.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

withCredentials: PropTypes.bool

If set to true, enables passing credentials, as defined in the Fetch standard, in CORS requests that are sent by the browser. Note that Swagger UI cannot currently set cookies cross-domain (see swagger-js#1163) - as a result, you will have to rely on browser-supplied cookies (which this setting enables sending) that Swagger UI cannot control.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

oauth2RedirectUrl: PropTypes.string

Redirect url given as parameter to the oauth2 provider. Default the url refers to oauth2-redirect.html at the same path as the Swagger UI is available.

⚠️ This prop is currently only applied once, on mount. Changes to this prop's value will not be propagated to the underlying Swagger UI instance. A future version of this module will remove this limitation, and the change will not be considered a breaking change.

Limitations

• Not all configuration bindings are available.
• Some props are only applied on mount, and cannot be updated reliably.
• OAuth redirection handling is not supported.
• Topbar/Standalone mode is not supported.

We intend to address these limitations based on user demand, so please open an issue or pull request if you have a specific request.

Notes

• The package.json in the same folder as this README is not the manifest that should be used for releases - another manifest is generated at build-time and can be found in ./dist/.

---

For anything else, check the Swagger-UI repository.