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.
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.
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 respresented 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.
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.
Limitations
- Not all configuration bindings are available.
- OAuth redirection handling is not supported.
- Topbar/Standalone mode is not supported.
- Custom plugins are 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.