0
# OpenAPI Types
1

2
OpenAPI Types provides comprehensive TypeScript type definitions for OpenAPI (formerly Swagger) specifications across all major versions. It serves as the de facto standard type library for TypeScript developers working with OpenAPI documents, offering complete type safety and IntelliSense support for API specification parsing, validation, and generation tools.
3

4
## Package Information
5

6
- **Package Name**: openapi-types
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install openapi-types`
10

11
## Core Imports
12

13
```typescript
14
import { OpenAPI, OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { OpenAPI, OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } = require("openapi-types");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { OpenAPIV3, OpenAPIV3_1, OpenAPIV2 } from "openapi-types";
27

28
// Use version-specific types for targeted OpenAPI support
29
function processV3Document(doc: OpenAPIV3.Document) {
30
  console.log(`Processing OpenAPI 3.0 document: ${doc.info.title}`);
31
  // Access OpenAPI 3.0 specific features
32
}
33

34
function processV31Document(doc: OpenAPIV3_1.Document) {
35
  console.log(`Processing OpenAPI 3.1 document: ${doc.info.title}`);
36
  // Access OpenAPI 3.1 specific features like webhooks
37
  if (doc.webhooks) {
38
    console.log('Document has webhooks');
39
  }
40
}
41

42
function processV2Document(doc: OpenAPIV2.Document) {
43
  console.log(`Processing Swagger 2.0 document: ${doc.info.title}`);
44
  // Access Swagger 2.0 specific features
45
}
46

47
// Use generic types for version-agnostic code
48
import { OpenAPI } from "openapi-types";
49

50
function processAnyDocument(doc: OpenAPI.Document) {
51
  // Works with any OpenAPI version
52
  console.log(`Processing document: ${doc.info.title}`);
53
}
54
```
55

56
## Architecture
57

58
OpenAPI Types is organized around four main namespaces, each providing complete type coverage for their respective OpenAPI specification versions:
59

60
- **OpenAPI Namespace**: Generic union types that work across all OpenAPI versions
61
- **OpenAPIV3_1 Namespace**: Complete type definitions for OpenAPI 3.1 specification
62
- **OpenAPIV3 Namespace**: Complete type definitions for OpenAPI 3.0 specification  
63
- **OpenAPIV2 Namespace**: Complete type definitions for OpenAPI 2.0 (Swagger) specification
64
- **JSON Schema Support**: Base JSON Schema interface used by OpenAPIV2
65

66
All types support generic extensions via `<T extends {} = {}>` parameters, enabling custom extension properties throughout the API surface.
67

68
## Capabilities
69

70
### Generic OpenAPI Types
71

72
Cross-version union types for building version-agnostic OpenAPI tools and parsers. Ideal for libraries that need to support multiple OpenAPI specification versions.
73

74
```typescript { .api }
75
namespace OpenAPI {
76
  type Document<T extends {} = {}> = 
77
    | OpenAPIV2.Document<T>
78
    | OpenAPIV3.Document<T>
79
    | OpenAPIV3_1.Document<T>;
80
  
81
  type Operation<T extends {} = {}> =
82
    | OpenAPIV2.OperationObject<T>
83
    | OpenAPIV3.OperationObject<T>
84
    | OpenAPIV3_1.OperationObject<T>;
85
}
86
```
87

88
[Generic OpenAPI Types](./generic-types.md)
89

90
### OpenAPI 3.1 Types
91

92
Complete type definitions for the OpenAPI 3.1 specification with support for JSON Schema 2020-12, webhooks, and enhanced reference objects.
93

94
```typescript { .api }
95
namespace OpenAPIV3_1 {
96
  interface Document<T extends {} = {}> {
97
    openapi: string;
98
    info: InfoObject;
99
    jsonSchemaDialect?: string;
100
    servers?: ServerObject[];
101
    paths?: PathsObject<T>;
102
    webhooks?: Record<string, PathItemObject | ReferenceObject>;
103
    components?: ComponentsObject;
104
    security?: SecurityRequirementObject[];
105
    tags?: TagObject[];
106
    externalDocs?: ExternalDocumentationObject;
107
  }
108
}
109
```
110

111
[OpenAPI 3.1 Types](./openapi-v3_1.md)
112

113
### OpenAPI 3.0 Types
114

115
Complete type definitions for the OpenAPI 3.0 specification, the most widely adopted version of the OpenAPI specification.
116

117
```typescript { .api }
118
namespace OpenAPIV3 {
119
  interface Document<T extends {} = {}> {
120
    openapi: string;
121
    info: InfoObject;
122
    servers?: ServerObject[];
123
    paths: PathsObject<T>;
124
    components?: ComponentsObject;
125
    security?: SecurityRequirementObject[];
126
    tags?: TagObject[];
127
    externalDocs?: ExternalDocumentationObject;
128
  }
129
  
130
  enum HttpMethods {
131
    GET = 'get',
132
    PUT = 'put',
133
    POST = 'post',
134
    DELETE = 'delete',
135
    OPTIONS = 'options',
136
    HEAD = 'head',
137
    PATCH = 'patch',
138
    TRACE = 'trace'
139
  }
140
}
141
```
142

143
[OpenAPI 3.0 Types](./openapi-v3.md)
144

145
### OpenAPI 2.0 Types
146

147
Complete type definitions for the OpenAPI 2.0 (Swagger) specification, providing backward compatibility for legacy API specifications.
148

149
```typescript { .api }
150
namespace OpenAPIV2 {
151
  interface Document<T extends {} = {}> {
152
    swagger: string;
153
    info: InfoObject;
154
    host?: string;
155
    basePath?: string;
156
    schemes?: string[];
157
    consumes?: MimeTypes;
158
    produces?: MimeTypes;
159
    paths: PathsObject<T>;
160
    definitions?: DefinitionsObject;
161
    parameters?: ParametersDefinitionsObject;
162
    responses?: ResponsesDefinitionsObject;
163
    securityDefinitions?: SecurityDefinitionsObject;
164
    security?: SecurityRequirementObject[];
165
    tags?: TagObject[];
166
    externalDocs?: ExternalDocumentationObject;
167
  }
168
  
169
  enum HttpMethods {
170
    GET = 'get',
171
    PUT = 'put', 
172
    POST = 'post',
173
    DELETE = 'delete',
174
    OPTIONS = 'options',
175
    HEAD = 'head',
176
    PATCH = 'patch'
177
  }
178
}
179
```
180

181
[OpenAPI 2.0 Types](./openapi-v2.md)
182

183
### JSON Schema Types
184

185
Base JSON Schema interface supporting the schema definitions used throughout OpenAPI specifications.
186

187
```typescript { .api }
188
interface IJsonSchema {
189
  id?: string;
190
  $schema?: string;
191
  title?: string;
192
  description?: string;
193
  type?: string | string[];
194
  properties?: { [name: string]: IJsonSchema };
195
  required?: string[];
196
  additionalProperties?: boolean | IJsonSchema;
197
  items?: IJsonSchema | IJsonSchema[];
198
  enum?: any[];
199
  allOf?: IJsonSchema[];
200
  anyOf?: IJsonSchema[];
201
  oneOf?: IJsonSchema[];
202
  not?: IJsonSchema;
203
  $ref?: string;
204
}
205
```
206

207
[JSON Schema Types](./json-schema.md)