0
# Generic OpenAPI Types
1

2
Cross-version union types for building version-agnostic OpenAPI tools and parsers. These types enable libraries to work with multiple OpenAPI specification versions without requiring version-specific handling.
3

4
## Capabilities
5

6
### Document Type
7

8
Union type representing any OpenAPI document across all supported versions.
9

10
```typescript { .api }
11
/**
12
 * Generic OpenAPI document type supporting all specification versions
13
 * @template T - Extension object type for custom properties
14
 */
15
type Document<T extends {} = {}> = 
16
  | OpenAPIV2.Document<T>
17
  | OpenAPIV3.Document<T>
18
  | OpenAPIV3_1.Document<T>;
19
```
20

21
### Operation Type
22

23
Union type representing any OpenAPI operation object across all supported versions.
24

25
```typescript { .api }
26
/**
27
 * Generic OpenAPI operation type supporting all specification versions
28
 * @template T - Extension object type for custom properties
29
 */
30
type Operation<T extends {} = {}> =
31
  | OpenAPIV2.OperationObject<T>
32
  | OpenAPIV3.OperationObject<T>
33
  | OpenAPIV3_1.OperationObject<T>;
34
```
35

36
### Parameter Type
37

38
Union type representing any OpenAPI parameter across all supported versions.
39

40
```typescript { .api }
41
/**
42
 * Generic OpenAPI parameter type supporting all specification versions
43
 */
44
type Parameter =
45
  | OpenAPIV3_1.ReferenceObject
46
  | OpenAPIV3_1.ParameterObject
47
  | OpenAPIV3.ReferenceObject
48
  | OpenAPIV3.ParameterObject
49
  | OpenAPIV2.ReferenceObject
50
  | OpenAPIV2.Parameter;
51
```
52

53
### Parameters Type
54

55
Union type representing parameter arrays across all supported versions.
56

57
```typescript { .api }
58
/**
59
 * Generic OpenAPI parameters array type supporting all specification versions
60
 */
61
type Parameters =
62
  | (OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ParameterObject)[]
63
  | (OpenAPIV3.ReferenceObject | OpenAPIV3.ParameterObject)[]
64
  | (OpenAPIV2.ReferenceObject | OpenAPIV2.Parameter)[];
65
```
66

67
### Request Interface
68

69
Generic request object structure for OpenAPI request handling.
70

71
```typescript { .api }
72
/**
73
 * Generic request interface for OpenAPI request processing
74
 */
75
interface Request {
76
  /** Request body data */
77
  body?: any;
78
  /** Request headers object */
79
  headers?: object;
80
  /** Path parameters object */
81
  params?: object;
82
  /** Query parameters object */
83
  query?: object;
84
}
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { OpenAPI } from "openapi-types";
91

92
// Version-agnostic document processing
93
function getDocumentTitle(doc: OpenAPI.Document): string {
94
  return doc.info.title;
95
}
96

97
// Version-agnostic operation processing
98
function getOperationId(operation: OpenAPI.Operation): string | undefined {
99
  return operation.operationId;
100
}
101

102
// Generic parameter validation
103
function validateParameter(param: OpenAPI.Parameter): boolean {
104
  // Handle different parameter formats across versions
105
  if ('$ref' in param) {
106
    return true; // Reference object
107
  }
108
  return param.name != null && param.in != null;
109
}
110

111
// Request processing
112
function processRequest(req: OpenAPI.Request) {
113
  console.log('Body:', req.body);
114
  console.log('Headers:', req.headers);
115
  console.log('Params:', req.params);
116
  console.log('Query:', req.query);
117
}
118
```