0
# OpenAPI 2.0 Types
1

2
Complete type definitions for the OpenAPI 2.0 (Swagger) specification, providing backward compatibility support for legacy API specifications and tooling.
3

4
## Capabilities
5

6
### Document Structure
7

8
Core document type representing the root OpenAPI 2.0 specification document.
9

10
```typescript { .api }
11
/**
12
 * Root OpenAPI 2.0 (Swagger) document structure
13
 * @template T - Extension object type for custom properties
14
 */
15
interface Document<T extends {} = {}> {
16
  swagger: string;
17
  info: InfoObject;
18
  host?: string;
19
  basePath?: string;
20
  schemes?: string[];
21
  consumes?: MimeTypes;
22
  produces?: MimeTypes;
23
  paths: PathsObject<T>;
24
  definitions?: DefinitionsObject;
25
  parameters?: ParametersDefinitionsObject;
26
  responses?: ResponsesDefinitionsObject;
27
  securityDefinitions?: SecurityDefinitionsObject;
28
  security?: SecurityRequirementObject[];
29
  tags?: TagObject[];
30
  externalDocs?: ExternalDocumentationObject;
31
  'x-express-openapi-additional-middleware'?: (
32
    | ((request: any, response: any, next: any) => Promise<void>)
33
    | ((request: any, response: any, next: any) => void)
34
  )[];
35
  'x-express-openapi-validation-strict'?: boolean;
36
}
37
```
38

39
### Info and Metadata Objects
40

41
API metadata and information structures for Swagger 2.0.
42

43
```typescript { .api }
44
/**
45
 * API information object
46
 */
47
interface InfoObject {
48
  title: string;
49
  description?: string;
50
  termsOfService?: string;
51
  contact?: ContactObject;
52
  license?: LicenseObject;
53
  version: string;
54
}
55

56
/**
57
 * Contact information object
58
 */
59
interface ContactObject {
60
  name?: string;
61
  url?: string;
62
  email?: string;
63
}
64

65
/**
66
 * License information object
67
 */
68
interface LicenseObject {
69
  name: string;
70
  url?: string;
71
}
72

73
/**
74
 * Tag object for grouping operations
75
 */
76
interface TagObject {
77
  name: string;  
78
  description?: string;
79
  externalDocs?: ExternalDocumentationObject;
80
}
81

82
/**
83
 * External documentation object
84
 */
85
interface ExternalDocumentationObject {
86
  [index: string]: any;
87
  description?: string;
88
  url: string;
89
}
90
```
91

92
### Path and Operation Objects
93

94
Path definitions and HTTP operations for Swagger 2.0.
95

96
```typescript { .api }
97
/**
98
 * Collection of API paths
99
 * @template T - Extension object type for custom properties
100
 */
101
interface PathsObject<T extends {} = {}> {
102
  [index: string]: PathItemObject<T>;
103
}
104

105
/**
106
 * HTTP methods enumeration for Swagger 2.0
107
 */
108
enum HttpMethods {
109
  GET = 'get',
110
  PUT = 'put',
111
  POST = 'post',
112
  DELETE = 'delete',
113
  OPTIONS = 'options',
114
  HEAD = 'head',
115
  PATCH = 'patch'
116
}
117

118
/**
119
 * Path item object with operation definitions
120
 * @template T - Extension object type for custom properties
121
 */
122
type PathItemObject<T extends {} = {}> = {
123
  $ref?: string;
124
  parameters?: Parameters;
125
} & {
126
  [method in HttpMethods]?: OperationObject<T>;
127
};
128

129
/**
130
 * HTTP operation object
131
 * @template T - Extension object type for custom properties
132
 */
133
type OperationObject<T extends {} = {}> = {
134
  tags?: string[];
135
  summary?: string;
136
  description?: string;
137
  externalDocs?: ExternalDocumentationObject;
138
  operationId?: string;
139
  consumes?: MimeTypes;
140
  produces?: MimeTypes;
141
  parameters?: Parameters;
142
  responses: ResponsesObject;
143
  schemes?: string[];
144
  deprecated?: boolean;
145
  security?: SecurityRequirementObject[];
146
} & T;
147

148
/**
149
 * MIME types array
150
 */
151
type MimeTypes = string[];
152
```
153

154
### Parameter Objects
155

156
Parameter definitions for Swagger 2.0.
157

158
```typescript { .api }
159
/**
160
 * Parameters array type
161
 */
162
type Parameters = (ReferenceObject | Parameter)[];
163

164
/**
165
 * Parameter union type
166
 */
167
type Parameter = InBodyParameterObject | GeneralParameterObject;
168

169
/**
170
 * Base parameter object
171
 */
172
interface ParameterObject {
173
  name: string;
174
  in: string;
175
  description?: string;
176
  required?: boolean;
177
  [index: string]: any;
178
}
179

180
/**
181
 * In-body parameter object
182
 */
183
interface InBodyParameterObject extends ParameterObject {
184
  schema: Schema;
185
}
186

187
/**
188
 * General parameter object
189
 */
190
interface GeneralParameterObject extends ParameterObject, ItemsObject {
191
  allowEmptyValue?: boolean;
192
}
193

194
/**
195
 * Parameter definitions collection
196
 */
197
interface ParametersDefinitionsObject {
198
  [index: string]: ParameterObject;
199
}
200
```
201

202
### Schema System
203

204
JSON Schema objects for Swagger 2.0.
205

206
```typescript { .api }
207
/**
208
 * Schema union type
209
 */
210
type Schema = SchemaObject | ReferenceObject;
211

212
/**
213
 * Schema definitions collection
214
 */
215
interface DefinitionsObject {
216
  [index: string]: SchemaObject;
217
}
218

219
/**
220
 * Schema object extending JSON Schema
221
 */
222
interface SchemaObject extends IJsonSchema {
223
  [index: string]: any;
224
  discriminator?: string;
225
  readOnly?: boolean;
226
  xml?: XMLObject;
227
  externalDocs?: ExternalDocumentationObject;
228
  example?: any;
229
  default?: any;
230
  items?: ItemsObject | ReferenceObject;
231
  properties?: {
232
    [name: string]: SchemaObject;
233
  };
234
}
235

236
/**
237
 * Items object for array definitions
238
 */
239
interface ItemsObject {
240
  type: string;
241
  format?: string;
242
  items?: ItemsObject | ReferenceObject;
243
  collectionFormat?: string;
244
  default?: any;
245
  maximum?: number;
246
  exclusiveMaximum?: boolean;
247
  minimum?: number;
248
  exclusiveMinimum?: boolean;
249
  maxLength?: number;
250
  minLength?: number;
251
  pattern?: string;
252
  maxItems?: number;
253
  minItems?: number;
254
  uniqueItems?: boolean;
255
  enum?: any[];
256
  multipleOf?: number;
257
  $ref?: string;
258
}
259

260
/**
261
 * XML metadata object
262
 */
263
interface XMLObject {
264
  [index: string]: any;
265
  name?: string;
266
  namespace?: string;
267
  prefix?: string;
268
  attribute?: boolean;
269
  wrapped?: boolean;
270
}
271
```
272

273
### Reference and Response Objects
274

275
Reference objects and response definitions.
276

277
```typescript { .api }
278
/**
279
 * JSON Reference object
280
 */
281
interface ReferenceObject {
282
  $ref: string;
283
}
284

285
/**
286
 * Response union type
287
 */
288
type Response = ResponseObject | ReferenceObject;
289

290
/**
291
 * Collection of response objects
292
 */
293
interface ResponsesObject {
294
  [index: string]: Response | undefined;
295
  default?: Response;
296
}
297

298
/**
299
 * Response definitions collection
300
 */
301
interface ResponsesDefinitionsObject {
302
  [index: string]: ResponseObject;
303
}
304

305
/**
306
 * Response object definition
307
 */
308
interface ResponseObject {
309
  description: string;
310
  schema?: Schema;
311
  headers?: HeadersObject;
312
  examples?: ExampleObject;
313
}
314

315
/**
316
 * Headers collection object
317
 */
318
interface HeadersObject {
319
  [index: string]: HeaderObject;
320
}
321

322
/**
323
 * Header object definition
324
 */
325
interface HeaderObject extends ItemsObject {
326
  description?: string;
327
}
328

329
/**
330
 * Example object
331
 */
332
interface ExampleObject {
333
  [index: string]: any;
334
}
335
```
336

337
### Security Objects
338

339
Security definitions and requirements for Swagger 2.0.
340

341
```typescript { .api }
342
/**
343
 * Security definitions collection
344
 */
345
interface SecurityDefinitionsObject {
346
  [index: string]: SecuritySchemeObject;
347
}
348

349
/**
350
 * Security requirement object
351
 */
352
interface SecurityRequirementObject {
353
  [index: string]: string[];
354
}
355

356
/**
357
 * Security scheme object union type
358
 */
359
type SecuritySchemeObject =
360
  | SecuritySchemeBasic
361
  | SecuritySchemeApiKey
362
  | SecuritySchemeOauth2;
363

364
/**
365
 * Base security scheme object
366
 */
367
interface SecuritySchemeObjectBase {
368
  type: 'basic' | 'apiKey' | 'oauth2';
369
  description?: string;
370
}
371

372
/**
373
 * Basic authentication security scheme
374
 */
375
interface SecuritySchemeBasic extends SecuritySchemeObjectBase {
376
  type: 'basic';
377
}
378

379
/**
380
 * API key authentication security scheme
381
 */
382
interface SecuritySchemeApiKey extends SecuritySchemeObjectBase {
383
  type: 'apiKey';
384
  name: string;
385
  in: string;
386
}
387

388
/**
389
 * OAuth2 security scheme union type
390
 */
391
type SecuritySchemeOauth2 =
392
  | SecuritySchemeOauth2Implicit
393
  | SecuritySchemeOauth2AccessCode
394
  | SecuritySchemeOauth2Password
395
  | SecuritySchemeOauth2Application;
396

397
/**
398
 * OAuth2 scopes object
399
 */
400
interface ScopesObject {
401
  [index: string]: any;
402
}
403

404
/**
405
 * Base OAuth2 security scheme
406
 */
407
interface SecuritySchemeOauth2Base extends SecuritySchemeObjectBase {
408
  type: 'oauth2';
409
  flow: 'implicit' | 'password' | 'application' | 'accessCode';
410
  scopes: ScopesObject;
411
}
412

413
/**
414
 * OAuth2 implicit flow security scheme
415
 */
416
interface SecuritySchemeOauth2Implicit extends SecuritySchemeOauth2Base {
417
  flow: 'implicit';
418
  authorizationUrl: string;
419
}
420

421
/**
422
 * OAuth2 authorization code flow security scheme
423
 */
424
interface SecuritySchemeOauth2AccessCode extends SecuritySchemeOauth2Base {
425
  flow: 'accessCode';
426
  authorizationUrl: string;
427
  tokenUrl: string;
428
}
429

430
/**
431
 * OAuth2 password flow security scheme
432
 */
433
interface SecuritySchemeOauth2Password extends SecuritySchemeOauth2Base {
434
  flow: 'password';
435
  tokenUrl: string;
436
}
437

438
/**
439
 * OAuth2 client credentials flow security scheme
440
 */
441
interface SecuritySchemeOauth2Application extends SecuritySchemeOauth2Base {
442
  flow: 'application';
443
  tokenUrl: string;
444
}
445
```
446

447
**Usage Examples:**
448

449
```typescript
450
import { OpenAPIV2 } from "openapi-types";
451

452
// Swagger 2.0 document
453
const swaggerDoc: OpenAPIV2.Document = {
454
  swagger: "2.0",
455
  info: {
456
    title: "Pet Store API",
457
    version: "1.0.0",
458
    description: "A sample API for pet store operations"
459
  },
460
  host: "api.petstore.com",
461
  basePath: "/v1",
462
  schemes: ["https"],
463
  consumes: ["application/json"],
464
  produces: ["application/json"],
465
  paths: {
466
    "/pets": {
467
      get: {
468
        summary: "List all pets",
469
        operationId: "listPets",
470
        produces: ["application/json"],
471
        responses: {
472
          "200": {
473
            description: "A list of pets",
474
            schema: {
475
              type: "array",
476
              items: {
477
                $ref: "#/definitions/Pet"
478
              }
479
            }
480
          }
481
        }
482
      },
483
      post: {
484
        summary: "Create a pet",
485
        operationId: "createPet",
486
        consumes: ["application/json"],
487
        parameters: [
488
          {
489
            name: "pet",
490
            in: "body",
491
            required: true,
492
            schema: {
493
              $ref: "#/definitions/Pet"
494
            }
495
          }
496
        ],
497
        responses: {
498
          "201": {
499
            description: "Pet created",
500
            schema: {
501
              $ref: "#/definitions/Pet"
502
            }
503
          }
504
        }
505
      }
506
    }
507
  },
508
  definitions: {
509
    Pet: {
510
      type: "object",
511
      required: ["name"],
512
      properties: {
513
        id: {
514
          type: "integer",
515
          format: "int64"
516
        },
517
        name: {
518
          type: "string"
519
        },
520
        tag: {
521
          type: "string"
522
        }
523
      }
524
    }
525
  },
526
  securityDefinitions: {
527
    api_key: {
528
      type: "apiKey",
529
      name: "api_key",
530
      in: "header"
531
    },
532
    petstore_auth: {
533
      type: "oauth2",
534
      flow: "implicit",
535
      authorizationUrl: "https://petstore.swagger.io/oauth/authorize",
536
      scopes: {
537
        "write:pets": "modify pets in your account",
538
        "read:pets": "read your pets"
539
      }
540
    }
541
  }
542
};
543

544
// Using HTTP methods enum
545
function isValidMethod(method: string): method is OpenAPIV2.HttpMethods {
546
  return Object.values(OpenAPIV2.HttpMethods).includes(method as OpenAPIV2.HttpMethods);
547
}
548

549
// Parameter type checking
550
function isBodyParameter(param: OpenAPIV2.Parameter): param is OpenAPIV2.InBodyParameterObject {
551
  return 'schema' in param;
552
}
553

554
// Security scheme type checking
555
function isOAuth2Scheme(scheme: OpenAPIV2.SecuritySchemeObject): scheme is OpenAPIV2.SecuritySchemeOauth2 {
556
  return scheme.type === 'oauth2';
557
}
558
```