0
# Swagger UI React
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: swagger-ui-react
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install swagger-ui-react`
10

11
## Core Imports
12

13
```javascript
14
import SwaggerUI from "swagger-ui-react"
15
import "swagger-ui-react/swagger-ui.css"
16
```
17

18
For CommonJS:
19

20
```javascript
21
const SwaggerUI = require("swagger-ui-react")
22
require("swagger-ui-react/swagger-ui.css")
23
```
24

25
## Basic Usage
26

27
```javascript
28
import SwaggerUI from "swagger-ui-react"
29
import "swagger-ui-react/swagger-ui.css"
30

31
export default function App() {
32
  return (
33
    <SwaggerUI url="https://petstore.swagger.io/v2/swagger.json" />
34
  )
35
}
36
```
37

38
## Architecture
39

40
Swagger UI React is built around these key components:
41

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

48
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.
49

50
## Capabilities
51

52
### Main Component
53

54
The primary SwaggerUI React component for rendering OpenAPI documentation.
55

56
```javascript { .api }
57
function SwaggerUI(props: SwaggerUIProps): JSX.Element | null;
58

59
interface SwaggerUIProps {
60
  // Core content props
61
  spec?: string | object;
62
  url?: string;
63
  
64
  // Layout and display props
65
  layout?: string;
66
  docExpansion?: "list" | "full" | "none";
67
  defaultModelExpandDepth?: number;
68
  defaultModelsExpandDepth?: number;
69
  defaultModelRendering?: "example" | "model";
70
  displayOperationId?: boolean;
71
  showExtensions?: boolean;
72
  showCommonExtensions?: boolean;
73
  showMutatedRequest?: boolean;
74
  
75
  // Interaction props
76
  supportedSubmitMethods?: Array<"get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace">;
77
  tryItOutEnabled?: boolean;
78
  displayRequestDuration?: boolean;
79
  filter?: string | boolean;
80
  deepLinking?: boolean;
81
  
82
  // Network and security props
83
  requestInterceptor?: (req: any) => any | Promise<any>;
84
  responseInterceptor?: (res: any) => any | Promise<any>;
85
  withCredentials?: boolean;
86
  oauth2RedirectUrl?: string;
87
  persistAuthorization?: boolean;
88
  
89
  // Request snippets props
90
  requestSnippetsEnabled?: boolean;
91
  requestSnippets?: object;
92
  
93
  // Plugin system props
94
  plugins?: Array<object | Function> | Function;
95
  presets?: Array<Function>;
96
  queryConfigEnabled?: boolean;
97
  
98
  // Lifecycle props
99
  onComplete?: (system: any) => void;
100
  initialState?: object;
101
  uncaughtExceptionHandler?: Function;
102
}
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
// Basic usage with remote spec URL
109
<SwaggerUI url="https://petstore.swagger.io/v2/swagger.json" />
110

111
// Usage with inline spec object
112
const openApiSpec = {
113
  openapi: "3.0.0",
114
  info: { title: "My API", version: "1.0.0" },
115
  // ... rest of spec
116
}
117
<SwaggerUI spec={openApiSpec} />
118

119
// Advanced configuration
120
<SwaggerUI 
121
  url="https://api.example.com/openapi.json"
122
  docExpansion="list"
123
  defaultModelRendering="model"
124
  displayOperationId={true}
125
  tryItOutEnabled={true}
126
  filter={true}
127
  requestInterceptor={(req) => {
128
    req.headers.Authorization = "Bearer " + getAuthToken()
129
    return req
130
  }}
131
  onComplete={(system) => {
132
    console.log("Swagger UI loaded:", system)
133
  }}
134
/>
135
```
136

137
### Static System Access
138

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

141
```javascript { .api }
142
const System: typeof SwaggerUISystem;
143
```
144

145
**Usage Example:**
146

147
```javascript
148
import SwaggerUI from "swagger-ui-react"
149

150
// Access the System class for advanced usage
151
const system = new SwaggerUI.System({
152
  // system options
153
})
154
```
155

156
### Preset Collections
157

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

160
```javascript { .api }
161
const presets: {
162
  base: Function;
163
  apis: Function;
164
  [key: string]: Function;
165
};
166
```
167

168
**Usage Example:**
169

170
```javascript
171
import SwaggerUI from "swagger-ui-react"
172

173
// Use presets in advanced configuration
174
<SwaggerUI
175
  url="https://api.example.com/openapi.json"
176
  presets={[SwaggerUI.presets.apis, customPreset]}
177
/>
178
```
179

180
### Plugin Collections
181

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

184
```javascript { .api }
185
const plugins: {
186
  Auth: Function;
187
  Configs: Function;
188
  DeepLinking: Function;
189
  Err: Function;
190
  Filter: Function;
191
  Icons: Function;
192
  JSONSchema5: Function;
193
  JSONSchema5Samples: Function;
194
  JSONSchema202012: Function;
195
  JSONSchema202012Samples: Function;
196
  Layout: Function;
197
  Logs: Function;
198
  OpenAPI30: Function;
199
  OpenAPI31: Function;
200
  OnComplete: Function;
201
  RequestSnippets: Function;
202
  Spec: Function;
203
  SwaggerClient: Function;
204
  Util: Function;
205
  View: Function;
206
  ViewLegacy: Function;
207
  DownloadUrl: Function;
208
  SyntaxHighlighting: Function;
209
  Versions: Function;
210
  SafeRender: Function;
211
  [key: string]: Function;
212
};
213
```
214

215
**Usage Example:**
216

217
```javascript
218
import SwaggerUI from "swagger-ui-react"
219

220
// Use specific plugins in configuration
221
<SwaggerUI
222
  url="https://api.example.com/openapi.json"
223
  plugins={[SwaggerUI.plugins.Auth, SwaggerUI.plugins.RequestSnippets]}
224
/>
225
```
226

227
### Configuration Utilities
228

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

231
```javascript { .api }
232
const config: {
233
  defaults: object;
234
  merge: Function;
235
  typeCast: Function;
236
  typeCastMappings: object;
237
};
238
```
239

240
**Usage Example:**
241

242
```javascript
243
import SwaggerUI from "swagger-ui-react"
244

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

249
// Use merge utility for complex configurations
250
const mergedConfig = SwaggerUI.config.merge(
251
  SwaggerUI.config.defaults,
252
  { tryItOutEnabled: true, filter: true }
253
)
254
```
255

256
## Prop Details
257

258
### Core Content Props
259

260
**spec** - OpenAPI document as JavaScript object, JSON string, or YAML string
261
- Type: `string | object`
262
- Default: undefined
263
- Note: Don't use with `url` prop
264

265
**url** - Remote URL to OpenAPI document for fetching and parsing
266
- Type: `string`
267
- Default: undefined
268
- Note: Don't use with `spec` prop
269

270
### Layout Props
271

272
**layout** - Name of top-level layout component via plugin system
273
- Type: `string`
274
- Default: "BaseLayout"
275
- Note: Applied only on mount
276

277
**docExpansion** - Default expansion setting for operations and tags
278
- Type: `"list" | "full" | "none"`
279
- Default: "list"
280
- Note: Applied only on mount
281

282
**defaultModelExpandDepth** - Default expansion depth for models
283
- Type: `number`
284
- Default: 1
285
- Note: Set to -1 to completely hide models; applied only on mount
286

287
**defaultModelsExpandDepth** - Default expansion depth for models section
288
- Type: `number`
289
- Default: 1
290
- Note: Applied only on mount
291

292
**defaultModelRendering** - Default model rendering mode
293
- Type: `"example" | "model"`
294
- Default: "example"
295
- Note: Applied only on mount
296

297
### Interaction Props
298

299
**tryItOutEnabled** - Controls if Try it out section starts enabled
300
- Type: `boolean`
301
- Default: false
302
- Note: Applied only on mount
303

304
**supportedSubmitMethods** - HTTP methods with Try it out enabled
305
- Type: `Array<"get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace">`
306
- Default: All methods
307
- Note: Empty array disables Try it out for all operations; applied only on mount
308

309
**filter** - Enables/configures operation filtering
310
- Type: `string | boolean`
311
- Default: false
312
- Note: Boolean enables/disables, string sets filter expression
313

314
### Network Props
315

316
**requestInterceptor** - Function to intercept and modify requests
317
- Type: `(req: any) => any | Promise<any>`
318
- Default: undefined
319
- Parameters: req - Request object to modify
320
- Returns: Modified request object or Promise resolving to modified request
321

322
**responseInterceptor** - Function to intercept and modify responses
323
- Type: `(res: any) => any | Promise<any>`
324
- Default: undefined
325
- Parameters: res - Response object to modify  
326
- Returns: Modified response object or Promise resolving to modified response
327

328
**withCredentials** - Enables passing credentials in CORS requests
329
- Type: `boolean`
330
- Default: false
331
- Note: Applied only on mount
332

333
### Callback Props
334

335
**onComplete** - Callback triggered when Swagger UI finishes rendering
336
- Type: `(system: any) => void`
337
- Default: undefined
338
- Parameters: system - Swagger UI system object
339

340
## Error Handling
341

342
Swagger UI React handles errors through:
343

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

349
## Limitations
350

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

357
## Peer Dependencies
358

359
```json
360
{
361
  "react": ">=16.8.0 <20",
362
  "react-dom": ">=16.8.0 <20"
363
}
364
```