0
# Swagger Client
1

2
Swagger Client is a comprehensive JavaScript library that enables developers to fetch, resolve, and interact with Swagger/OpenAPI documents. It provides full support for OpenAPI specifications from version 2.0 through 3.1.0, offering capabilities for document resolution, API interaction, and spec validation.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import SwaggerClient from "swagger-client";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const SwaggerClient = require("swagger-client");
21
```
22

23
Individual components:
24

25
```javascript
26
import { 
27
  execute, 
28
  buildRequest, 
29
  resolve, 
30
  resolveSubtree,
31
  makeResolve,
32
  makeResolveSubtree,
33
  http,
34
  makeHttp 
35
} from "swagger-client";
36
```
37

38
Helper utilities:
39

40
```javascript
41
import {
42
  eachOperation,
43
  findOperation,
44
  getOperationRaw,
45
  opId,
46
  isHttpUrl,
47
  replaceSpecialCharsWithUnderscore
48
} from "swagger-client";
49
```
50

51
For browser UMD builds:
52

53
```html
54
<script src="https://unpkg.com/swagger-client@3.35.6/dist/swagger-client.browser.min.js"></script>
55
```
56

57
## Basic Usage
58

59
```javascript
60
import SwaggerClient from "swagger-client";
61

62
// Initialize client with a Swagger/OpenAPI spec URL
63
const client = await SwaggerClient({
64
  url: "https://petstore.swagger.io/v2/swagger.json"
65
});
66

67
// Execute an API operation
68
const response = await client.execute({
69
  operationId: "getPetById",
70
  parameters: {
71
    petId: 1
72
  }
73
});
74

75
console.log(response.body);
76
```
77

78
## Architecture
79

80
Swagger Client is built around several key components:
81

82
- **Main Constructor**: Creates client instances with spec resolution and interface generation
83
- **Resolver System**: Multiple strategies for resolving OpenAPI specs with different versions
84
- **HTTP Client**: Customizable HTTP implementation with request/response interceptors
85
- **Parameter Builders**: Version-specific parameter serialization for different OpenAPI versions
86
- **Interface Generation**: Creates convenient tag-based APIs for easier consumption
87
- **ApiDOM Integration**: Advanced parsing and dereferencing capabilities using ApiDOM
88

89
## Runtime Support
90

91
### Node.js
92
- Requires Node.js >=12.20.0
93
- Uses native fetch (>=18) or node-fetch (12.20.0-17.x)
94

95
### Browsers
96
- Chrome, Safari, Firefox, Edge (latest versions)
97
- Uses native browser fetch API
98

99
## Capabilities
100

101
### Client Construction
102

103
Creates SwaggerClient instances with automatic spec resolution and interface generation.
104

105
```javascript { .api }
106
function SwaggerClient(options?: SwaggerClientOptions): Promise<SwaggerClientInstance>;
107

108
interface SwaggerClientOptions {
109
  url?: string;
110
  spec?: object;
111
  authorizations?: SecurityAuthorizations;
112
  requestInterceptor?: RequestInterceptor;
113
  responseInterceptor?: ResponseInterceptor;
114
  allowMetaPatches?: boolean;
115
  useCircularStructures?: boolean;
116
  http?: HttpClient;
117
  fetch?: FetchFunction;
118
  userFetch?: FetchFunction;
119
  disableInterfaces?: boolean;
120
  skipNormalization?: boolean;
121
  pathDiscriminator?: string[];
122
  v2OperationIdCompatibilityMode?: boolean;
123
}
124

125
interface SwaggerClientInstance {
126
  spec: object;
127
  originalSpec?: object;
128
  errors: ResolutionError[];
129
  apis: TaggedOperations;
130
  authorizations?: SecurityAuthorizations;
131
  execute(options: ExecutionOptions): Promise<ResponseObject>;
132
  resolve(options?: ResolveOptions): Promise<SwaggerClientInstance>;
133
}
134
```
135

136
[Client Construction and Configuration](./client-construction.md)
137

138
### API Execution
139

140
Execute operations against OpenAPI specs with parameter handling and security.
141

142
```javascript { .api }
143
function execute(options: ExecutionOptions): Promise<ResponseObject>;
144

145
interface ExecutionOptions {
146
  spec: object;
147
  operationId?: string;
148
  pathName?: string;
149
  method?: string;
150
  parameters?: ParameterValues;
151
  securities?: SecurityRequirements;
152
  requestInterceptor?: RequestInterceptor;
153
  responseInterceptor?: ResponseInterceptor;
154
  contextUrl?: string;
155
  http?: HttpClient;
156
  fetch?: FetchFunction;
157
  userFetch?: FetchFunction;
158
}
159

160
interface ResponseObject {
161
  url: string;
162
  method: string;
163
  status: number;
164
  statusText: string;
165
  headers: Record<string, string>;
166
  text: string;
167
  body: any;
168
  obj: any;
169
  ok: boolean;
170
  data: any;
171
}
172
```
173

174
[API Execution and Operations](./execution.md)
175

176
### Spec Resolution
177

178
Resolve OpenAPI specifications with reference handling and validation.
179

180
```javascript { .api }
181
function resolve(options: ResolveOptions): Promise<ResolutionResult>;
182

183
interface ResolveOptions {
184
  spec?: object;
185
  url?: string;
186
  http?: HttpClient;
187
  fetch?: FetchFunction;
188
  allowMetaPatches?: boolean;
189
  useCircularStructures?: boolean;
190
  requestInterceptor?: RequestInterceptor;
191
  responseInterceptor?: ResponseInterceptor;
192
  skipNormalization?: boolean;
193
  pathDiscriminator?: string[];
194
}
195

196
interface ResolutionResult {
197
  spec: object;
198
  errors: ResolutionError[];
199
}
200
```
201

202
[Spec Resolution and Processing](./resolution.md)
203

204
### HTTP Client
205

206
Customizable HTTP client with request/response serialization and interceptors.
207

208
```javascript { .api }
209
function http(url: string, options?: HttpOptions): Promise<ResponseObject>;
210
function makeHttp(httpFn: HttpFunction, preFetch?: Function, postFetch?: Function): HttpFunction;
211

212
interface HttpOptions {
213
  method?: string;
214
  headers?: Record<string, string>;
215
  body?: any;
216
  credentials?: RequestCredentials;
217
  requestInterceptor?: RequestInterceptor;
218
  responseInterceptor?: ResponseInterceptor;
219
  userFetch?: FetchFunction;
220
  signal?: AbortSignal;
221
}
222
```
223

224
[HTTP Client and Request Handling](./http-client.md)
225

226
### Request Building
227

228
Build HTTP requests from OpenAPI operations and parameters.
229

230
```javascript { .api }
231
function buildRequest(options: BuildRequestOptions): RequestObject;
232

233
interface BuildRequestOptions {
234
  spec: object;
235
  operationId: string;
236
  parameters?: ParameterValues;
237
  securities?: SecurityRequirements;
238
  baseURL?: string;
239
  contextUrl?: string;
240
  http?: HttpClient;
241
  requestInterceptor?: RequestInterceptor;
242
  responseInterceptor?: ResponseInterceptor;
243
  userFetch?: FetchFunction;
244
  signal?: AbortSignal;
245
}
246

247
interface RequestObject {
248
  url: string;
249
  method: string;
250
  headers: Record<string, string>;
251
  body?: any;
252
  credentials: RequestCredentials;
253
}
254
```
255

256
[Request Building and Parameters](./request-building.md)
257

258
### Helper Utilities
259

260
Utility functions for working with OpenAPI specs and operations.
261

262
```javascript { .api }
263
const SwaggerClient.helpers: {
264
  opId(operation: OperationObject, pathName: string, method: string, options?: OpIdOptions): string;
265
};
266

267
function eachOperation(spec: object, callback: OperationCallback, find?: boolean): OperationInfo | undefined;
268
function findOperation(spec: object, predicate: OperationPredicate): OperationInfo | undefined;
269
function getOperationRaw(spec: object, operationId: string): OperationInfo | undefined;
270
function opId(operation: OperationObject, pathName: string, method: string, options?: OpIdOptions): string;
271
function idFromPathMethod(pathName: string, method: string): string;
272
function idFromPathMethodLegacy(pathName: string, method: string): string;
273
function isHttpUrl(url: string): boolean;
274
```
275

276
[Helper Utilities and Spec Analysis](./helpers.md)
277

278
## Common Types
279

280
```javascript { .api }
281
interface SecurityAuthorizations {
282
  [securityName: string]: SecurityValue;
283
}
284

285
interface SecurityValue {
286
  username?: string;
287
  password?: string;
288
  clientId?: string;
289
  clientSecret?: string;
290
  value?: string;
291
}
292

293
interface ParameterValues {
294
  [parameterName: string]: any;
295
}
296

297
interface RequestInterceptor {
298
  (request: RequestObject): RequestObject | Promise<RequestObject>;
299
}
300

301
interface ResponseInterceptor {
302
  (response: ResponseObject): ResponseObject | Promise<ResponseObject>;
303
}
304

305
interface ResolutionError {
306
  message: string;
307
  fullPath: string[];
308
}
309

310
interface TaggedOperations {
311
  [tagName: string]: {
312
    [operationId: string]: (parameters?: ParameterValues, options?: ExecutionOptions) => Promise<ResponseObject>;
313
  };
314
}
315
```