0
# OpenAPI 3.0 Types
1

2
Complete type definitions for the OpenAPI 3.0 specification, the most widely adopted version of the OpenAPI specification. Provides comprehensive type coverage for modern REST API documentation and tooling.
3

4
## Capabilities
5

6
### Document Structure
7

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

10
```typescript { .api }
11
/**
12
 * Root OpenAPI 3.0 document structure
13
 * @template T - Extension object type for custom properties
14
 */
15
interface Document<T extends {} = {}> {
16
  openapi: string;
17
  info: InfoObject;
18
  servers?: ServerObject[];
19
  paths: PathsObject<T>;
20
  components?: ComponentsObject;
21
  security?: SecurityRequirementObject[];
22
  tags?: TagObject[];
23
  externalDocs?: ExternalDocumentationObject;
24
  'x-express-openapi-additional-middleware'?: (
25
    | ((request: any, response: any, next: any) => Promise<void>)
26
    | ((request: any, response: any, next: any) => void)
27
  )[];
28
  'x-express-openapi-validation-strict'?: boolean;
29
}
30
```
31

32
### Info and Metadata Objects
33

34
API metadata and information structures.
35

36
```typescript { .api }
37
/**
38
 * API information object
39
 */
40
interface InfoObject {
41
  title: string;
42
  description?: string;
43
  termsOfService?: string;
44
  contact?: ContactObject;
45
  license?: LicenseObject;
46
  version: string;
47
}
48

49
/**
50
 * Contact information object
51
 */
52
interface ContactObject {
53
  name?: string;
54
  url?: string;
55
  email?: string;
56
}
57

58
/**
59
 * License information object
60
 */
61
interface LicenseObject {
62
  name: string;
63
  url?: string;
64
}
65

66
/**
67
 * External documentation object
68
 */
69
interface ExternalDocumentationObject {
70
  description?: string;
71
  url: string;
72
}
73

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

84
### Server Configuration
85

86
Server and server variable definitions.
87

88
```typescript { .api }
89
/**
90
 * Server configuration object
91
 */
92
interface ServerObject {
93
  url: string;
94
  description?: string;
95
  variables?: { [variable: string]: ServerVariableObject };
96
}
97

98
/**
99
 * Server variable object
100
 */
101
interface ServerVariableObject {
102
  enum?: string[];
103
  default: string;
104
  description?: string;
105
}
106
```
107

108
### Path and Operation Objects
109

110
Path definitions and HTTP operations.
111

112
```typescript { .api }
113
/**
114
 * Collection of API paths
115
 * @template T - Extension object type for custom properties
116
 * @template P - Path-level extension object type
117
 */
118
interface PathsObject<T extends {} = {}, P extends {} = {}> {
119
  [pattern: string]: (PathItemObject<T> & P) | undefined;
120
}
121

122
/**
123
 * HTTP methods enumeration
124
 */
125
enum HttpMethods {
126
  GET = 'get',
127
  PUT = 'put',
128
  POST = 'post',
129
  DELETE = 'delete',
130
  OPTIONS = 'options',
131
  HEAD = 'head',
132
  PATCH = 'patch',
133
  TRACE = 'trace'
134
}
135

136
/**
137
 * Path item object with operation definitions
138
 * @template T - Extension object type for custom properties
139
 */
140
type PathItemObject<T extends {} = {}> = {
141
  $ref?: string;
142
  summary?: string;
143
  description?: string;
144
  servers?: ServerObject[];
145
  parameters?: (ReferenceObject | ParameterObject)[];
146
} & {
147
  [method in HttpMethods]?: OperationObject<T>;
148
};
149

150
/**
151
 * HTTP operation object
152
 * @template T - Extension object type for custom properties
153
 */
154
type OperationObject<T extends {} = {}> = {
155
  tags?: string[];
156
  summary?: string;
157
  description?: string;
158
  externalDocs?: ExternalDocumentationObject;
159
  operationId?: string;
160
  parameters?: (ReferenceObject | ParameterObject)[];
161
  requestBody?: ReferenceObject | RequestBodyObject;
162
  responses: ResponsesObject;
163
  callbacks?: { [callback: string]: ReferenceObject | CallbackObject };
164
  deprecated?: boolean;
165
  security?: SecurityRequirementObject[];
166
  servers?: ServerObject[];
167
} & T;
168
```
169

170
### Parameter Objects
171

172
Parameter definitions and base parameter properties.
173

174
```typescript { .api }
175
/**
176
 * Parameter object
177
 */
178
interface ParameterObject extends ParameterBaseObject {
179
  name: string;
180
  in: string;
181
}
182

183
/**
184
 * Header object
185
 */
186
interface HeaderObject extends ParameterBaseObject {}
187

188
/**
189
 * Base parameter object with common properties
190
 */
191
interface ParameterBaseObject {
192
  description?: string;
193
  required?: boolean;
194
  deprecated?: boolean;
195
  allowEmptyValue?: boolean;
196
  style?: string;
197
  explode?: boolean;
198
  allowReserved?: boolean;
199
  schema?: ReferenceObject | SchemaObject;
200
  example?: any;
201
  examples?: { [media: string]: ReferenceObject | ExampleObject };
202
  content?: { [media: string]: MediaTypeObject };
203
}
204
```
205

206
### Schema System
207

208
JSON Schema objects for OpenAPI 3.0.
209

210
```typescript { .api }
211
/**
212
 * Schema object union type
213
 */
214
type SchemaObject = ArraySchemaObject | NonArraySchemaObject;
215

216
/**
217
 * Array schema object
218
 */
219
interface ArraySchemaObject extends BaseSchemaObject {
220
  type: 'array';
221
  items: ReferenceObject | SchemaObject;
222
}
223

224
/**
225
 * Non-array schema object
226
 */
227
interface NonArraySchemaObject extends BaseSchemaObject {
228
  type?: 'boolean' | 'object' | 'number' | 'string' | 'integer';
229
}
230

231
/**
232
 * Base schema object with JSON schema properties
233
 */
234
interface BaseSchemaObject {
235
  title?: string;
236
  description?: string;
237
  format?: string;
238
  default?: any;
239
  multipleOf?: number;
240
  maximum?: number;
241
  exclusiveMaximum?: boolean;
242
  minimum?: number;
243
  exclusiveMinimum?: boolean;
244
  maxLength?: number;
245
  minLength?: number;
246
  pattern?: string;
247
  additionalProperties?: boolean | ReferenceObject | SchemaObject;
248
  maxItems?: number;
249
  minItems?: number;
250
  uniqueItems?: boolean;
251
  maxProperties?: number;
252
  minProperties?: number;
253
  required?: string[];
254
  enum?: any[];
255
  properties?: { [name: string]: ReferenceObject | SchemaObject };
256
  allOf?: (ReferenceObject | SchemaObject)[];
257
  oneOf?: (ReferenceObject | SchemaObject)[];
258
  anyOf?: (ReferenceObject | SchemaObject)[];
259
  not?: ReferenceObject | SchemaObject;
260
  nullable?: boolean;
261
  discriminator?: DiscriminatorObject;
262
  readOnly?: boolean;
263
  writeOnly?: boolean;
264
  xml?: XMLObject;
265
  externalDocs?: ExternalDocumentationObject;
266
  example?: any;
267
  deprecated?: boolean;
268
}
269

270
/**
271
 * Discriminator object for polymorphism
272
 */
273
interface DiscriminatorObject {
274
  propertyName: string;
275
  mapping?: { [value: string]: string };
276
}
277

278
/**
279
 * XML metadata object
280
 */
281
interface XMLObject {
282
  name?: string;
283
  namespace?: string;
284
  prefix?: string;
285
  attribute?: boolean;
286
  wrapped?: boolean;
287
}
288
```
289

290
### Reference and Example Objects
291

292
Reference objects and example definitions.
293

294
```typescript { .api }
295
/**
296
 * JSON Reference object
297
 */
298
interface ReferenceObject {
299
  $ref: string;
300
}
301

302
/**
303
 * Example object
304
 */
305
interface ExampleObject {
306
  summary?: string;
307
  description?: string;
308
  value?: any;
309
  externalValue?: string;
310
}
311
```
312

313
### Request and Response Objects
314

315
Request body and response definitions.
316

317
```typescript { .api }
318
/**
319
 * Request body object
320
 */
321
interface RequestBodyObject {
322
  description?: string;
323
  content: { [media: string]: MediaTypeObject };
324
  required?: boolean;
325
}
326

327
/**
328
 * Collection of response objects
329
 */
330
interface ResponsesObject {
331
  [code: string]: ReferenceObject | ResponseObject;
332
}
333

334
/**
335
 * Response object definition
336
 */
337
interface ResponseObject {
338
  description: string;
339
  headers?: { [header: string]: ReferenceObject | HeaderObject };
340
  content?: { [media: string]: MediaTypeObject };
341
  links?: { [link: string]: ReferenceObject | LinkObject };
342
}
343

344
/**
345
 * Media type object
346
 */
347
interface MediaTypeObject {
348
  schema?: ReferenceObject | SchemaObject;
349
  example?: any;
350
  examples?: { [media: string]: ReferenceObject | ExampleObject };
351
  encoding?: { [media: string]: EncodingObject };
352
}
353

354
/**
355
 * Encoding object for multipart/form-data
356
 */
357
interface EncodingObject {
358
  contentType?: string;
359
  headers?: { [header: string]: ReferenceObject | HeaderObject };
360
  style?: string;
361
  explode?: boolean;
362
  allowReserved?: boolean;
363
}
364

365
/**
366
 * Link object for response linking
367
 */
368
interface LinkObject {
369
  operationRef?: string;
370
  operationId?: string;
371
  parameters?: { [parameter: string]: any };
372
  requestBody?: any;
373
  description?: string;
374
  server?: ServerObject;
375
}
376

377
/**
378
 * Callback object for webhooks
379
 */
380
interface CallbackObject {
381
  [url: string]: PathItemObject;
382
}
383
```
384

385
### Security Objects
386

387
Security requirement and scheme definitions.
388

389
```typescript { .api }
390
/**
391
 * Security requirement object
392
 */
393
interface SecurityRequirementObject {
394
  [name: string]: string[];
395
}
396

397
/**
398
 * Security scheme object union type
399
 */
400
type SecuritySchemeObject =
401
  | HttpSecurityScheme
402
  | ApiKeySecurityScheme
403
  | OAuth2SecurityScheme
404
  | OpenIdSecurityScheme;
405

406
/**
407
 * HTTP security scheme
408
 */
409
interface HttpSecurityScheme {
410
  type: 'http';
411
  description?: string;
412
  scheme: string;
413
  bearerFormat?: string;
414
}
415

416
/**
417
 * API key security scheme
418
 */
419
interface ApiKeySecurityScheme {
420
  type: 'apiKey';
421
  description?: string;
422
  name: string;
423
  in: string;
424
}
425

426
/**
427
 * OAuth2 security scheme
428
 */
429
interface OAuth2SecurityScheme {
430
  type: 'oauth2';
431
  description?: string;
432
  flows: {
433
    implicit?: {
434
      authorizationUrl: string;
435
      refreshUrl?: string;
436
      scopes: { [scope: string]: string };
437
    };
438
    password?: {
439
      tokenUrl: string;
440
      refreshUrl?: string;
441
      scopes: { [scope: string]: string };
442
    };
443
    clientCredentials?: {
444
      tokenUrl: string;
445
      refreshUrl?: string;
446
      scopes: { [scope: string]: string };
447
    };
448
    authorizationCode?: {
449
      authorizationUrl: string;
450
      tokenUrl: string;
451
      refreshUrl?: string;
452
      scopes: { [scope: string]: string };
453
    };
454
  };
455
}
456

457
/**
458
 * OpenID Connect security scheme
459
 */
460
interface OpenIdSecurityScheme {
461
  type: 'openIdConnect';
462
  description?: string;
463
  openIdConnectUrl: string;
464
}
465
```
466

467
### Components Object
468

469
Reusable components collection.
470

471
```typescript { .api }
472
/**
473
 * Reusable components object
474
 */
475
interface ComponentsObject {
476
  schemas?: { [key: string]: ReferenceObject | SchemaObject };
477
  responses?: { [key: string]: ReferenceObject | ResponseObject };
478
  parameters?: { [key: string]: ReferenceObject | ParameterObject };
479
  examples?: { [key: string]: ReferenceObject | ExampleObject };
480
  requestBodies?: { [key: string]: ReferenceObject | RequestBodyObject };
481
  headers?: { [key: string]: ReferenceObject | HeaderObject };
482
  securitySchemes?: { [key: string]: ReferenceObject | SecuritySchemeObject };
483
  links?: { [key: string]: ReferenceObject | LinkObject };
484
  callbacks?: { [key: string]: ReferenceObject | CallbackObject };
485
}
486
```
487

488
**Usage Examples:**
489

490
```typescript
491
import { OpenAPIV3 } from "openapi-types";
492

493
// OpenAPI 3.0 document
494
const apiDoc: OpenAPIV3.Document = {
495
  openapi: "3.0.3",
496
  info: {
497
    title: "Pet Store API",
498
    version: "1.0.0",
499
    description: "A sample API for pet store operations"
500
  },
501
  servers: [
502
    {
503
      url: "https://api.petstore.com/v1",
504
      description: "Production server"
505
    }
506
  ],
507
  paths: {
508
    "/pets": {
509
      get: {
510
        summary: "List all pets",
511
        operationId: "listPets",
512
        responses: {
513
          "200": {
514
            description: "A list of pets",
515
            content: {
516
              "application/json": {
517
                schema: {
518
                  type: "array",
519
                  items: {
520
                    $ref: "#/components/schemas/Pet"
521
                  }
522
                }
523
              }
524
            }
525
          }
526
        }
527
      }
528
    }
529
  },
530
  components: {
531
    schemas: {
532
      Pet: {
533
        type: "object",
534
        required: ["id", "name"],
535
        properties: {
536
          id: {
537
            type: "integer",
538
            format: "int64"
539
          },
540
          name: {
541
            type: "string"
542
          },
543
          tag: {
544
            type: "string"
545
          }
546
        }
547
      }
548
    }
549
  }
550
};
551

552
// Using HTTP methods enum
553
function supportsMethod(method: string): method is OpenAPIV3.HttpMethods {
554
  return Object.values(OpenAPIV3.HttpMethods).includes(method as OpenAPIV3.HttpMethods);
555
}
556

557
// Schema validation
558
function isArraySchema(schema: OpenAPIV3.SchemaObject): schema is OpenAPIV3.ArraySchemaObject {
559
  return 'type' in schema && schema.type === 'array';
560
}
561
```