0
# OpenAPI TypeScript
1

2
OpenAPI TypeScript is a comprehensive TypeScript code generation tool that converts OpenAPI 3.0 and 3.1 schemas into accurate TypeScript type definitions. It provides both a programmatic API and CLI interface, enabling developers to automatically generate type-safe TypeScript interfaces from their OpenAPI specifications with extensive customization options and advanced features.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import openapiTS, { COMMENT_HEADER } from "openapi-typescript";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const openapiTS = require("openapi-typescript");
21
```
22

23
Transform functions:
24

25
```typescript
26
import { 
27
  transformSchema,
28
  transformSchemaObject,
29
  transformComponentsObject,
30
  transformPathsObject,
31
  transformOperationObject,
32
  astToString
33
} from "openapi-typescript";
34
```
35

36
## Basic Usage
37

38
### CLI Usage
39

40
```bash
41
# Generate types from local file
42
openapi-typescript ./api.yaml --output ./types.ts
43

44
# Generate types from URL
45
openapi-typescript https://api.example.com/openapi.json -o ./api-types.ts
46

47
# With advanced options
48
openapi-typescript ./api.yaml \
49
  --output ./types.ts \
50
  --export-type \
51
  --immutable \
52
  --enum
53
```
54

55
### Programmatic Usage
56

57
```typescript
58
import openapiTS, { astToString } from "openapi-typescript";
59
import fs from "node:fs";
60

61
// Convert schema to TypeScript AST
62
const ast = await openapiTS("./api.yaml", {
63
  exportType: true,
64
  immutable: true,
65
  enum: true
66
});
67

68
// Convert AST to TypeScript source code
69
const output = astToString(ast);
70

71
// Write to file
72
fs.writeFileSync("./types.ts", output);
73
```
74

75
## Architecture
76

77
OpenAPI TypeScript is built around several key components:
78

79
- **Core Converter**: Main `openapiTS()` function that orchestrates the conversion process
80
- **Transform Engine**: Modular transform functions for each OpenAPI specification object type
81
- **TypeScript AST Builder**: Utilities for creating and manipulating TypeScript AST nodes
82
- **CLI Interface**: Comprehensive command-line tool with extensive configuration options
83
- **Redocly Integration**: Schema validation and bundling using Redocly's OpenAPI core
84
- **Type System**: Complete support for all OpenAPI 3.0/3.1 features with accurate TypeScript mappings
85

86
## Capabilities
87

88
### Core Conversion
89

90
The main conversion functionality that transforms OpenAPI schemas into TypeScript AST nodes. Supports all input formats and provides extensive customization options.
91

92
```typescript { .api }
93
function openapiTS(
94
  source: string | URL | OpenAPI3 | Buffer | Readable,
95
  options?: OpenAPITSOptions
96
): Promise<ts.Node[]>;
97

98
interface OpenAPITSOptions {
99
  additionalProperties?: boolean;
100
  alphabetize?: boolean;
101
  arrayLength?: boolean;
102
  defaultNonNullable?: boolean;
103
  emptyObjectsUnknown?: boolean;
104
  enum?: boolean;
105
  enumValues?: boolean;
106
  dedupeEnums?: boolean;
107
  excludeDeprecated?: boolean;
108
  exportType?: boolean;
109
  immutable?: boolean;
110
  rootTypes?: boolean;
111
  rootTypesNoSchemaPrefix?: boolean;
112
  pathParamsAsTypes?: boolean;
113
  propertiesRequiredByDefault?: boolean;
114
  inject?: string;
115
  transform?: (schemaObject: SchemaObject, metadata: TransformNodeOptions) => ts.TypeNode;
116
  postTransform?: (ast: ts.Node[]) => ts.Node[];
117
  makePathsEnum?: boolean;
118
  generatePathParams?: boolean;
119
  silent?: boolean;
120
  cwd?: string | URL;
121
  redocly?: Config;
122
}
123

124
const COMMENT_HEADER: string;
125
```
126

127
[Core Conversion](./core-conversion.md)
128

129
### Schema Transforms
130

131
Transform functions for converting individual OpenAPI objects to TypeScript AST nodes. Essential for custom processing and advanced integrations.
132

133
```typescript { .api }
134
function transformSchema(schema: OpenAPI3, ctx: GlobalContext): ts.Node[];
135

136
function transformSchemaObject(
137
  schemaObject: SchemaObject | ReferenceObject,
138
  options: TransformNodeOptions
139
): ts.TypeNode;
140

141
function transformComponentsObject(
142
  componentsObject: ComponentsObject,
143
  ctx: GlobalContext
144
): ts.Node[];
145

146
function transformPathsObject(
147
  pathsObject: PathsObject,
148
  ctx: GlobalContext
149
): ts.TypeNode;
150
```
151

152
[Schema Transforms](./schema-transforms.md)
153

154
### TypeScript AST Utilities
155

156
Comprehensive utilities for creating and manipulating TypeScript AST nodes. Provides building blocks for custom transform functions and AST manipulation.
157

158
```typescript { .api }
159
function astToString(
160
  ast: ts.Node[], 
161
  options?: AstToStringOptions
162
): string;
163

164
function stringToAST(source: string): unknown[];
165

166
function tsLiteral(value: unknown): ts.TypeNode;
167
function tsUnion(types: ts.TypeNode[]): ts.TypeNode;
168
function tsIntersection(types: ts.TypeNode[]): ts.TypeNode;
169

170
interface AstToStringOptions {
171
  formatOptions?: FormatCodeSettings;
172
  banner?: string;
173
  footer?: string;
174
}
175
```
176

177
[TypeScript AST Utilities](./typescript-utilities.md)
178

179
### CLI Interface
180

181
Complete command-line interface with extensive configuration options for integration into build processes and development workflows.
182

183
```typescript { .api }
184
// CLI Options Interface (conceptual representation)
185
interface CLIOptions {
186
  help?: boolean;
187
  version?: boolean;
188
  output?: string;
189
  redocly?: string;
190
  check?: boolean;
191
  exportType?: boolean;
192
  immutable?: boolean;
193
  enum?: boolean;
194
  enumValues?: boolean;
195
  dedupeEnums?: boolean;
196
  additionalProperties?: boolean;
197
  emptyObjectsUnknown?: boolean;
198
  defaultNonNullable?: boolean;
199
  propertiesRequiredByDefault?: boolean;
200
  arrayLength?: boolean;
201
  pathParamsAsTypes?: boolean;
202
  alphabetize?: boolean;
203
  excludeDeprecated?: boolean;
204
  rootTypes?: boolean;
205
  rootTypesNoSchemaPrefix?: boolean;
206
  makePathsEnum?: boolean;
207
}
208
```
209

210
[CLI Interface](./cli-interface.md)
211

212
## Types
213

214
Core TypeScript type definitions for OpenAPI specification objects and configuration options.
215

216
```typescript { .api }
217
interface OpenAPI3 {
218
  openapi: string;
219
  info: InfoObject;
220
  jsonSchemaDialect?: string;
221
  servers?: ServerObject[];
222
  paths?: PathsObject;
223
  webhooks?: { [id: string]: PathItemObject | ReferenceObject };
224
  components?: ComponentsObject;
225
  security?: SecurityRequirementObject[];
226
  tags?: TagObject[];
227
  externalDocs?: ExternalDocumentationObject;
228
  $defs?: $defs;
229
}
230

231
interface GlobalContext {
232
  additionalProperties: boolean;
233
  alphabetize: boolean;
234
  arrayLength: boolean;
235
  defaultNonNullable: boolean;
236
  discriminators: Map<string, DiscriminatorObject>;
237
  emptyObjectsUnknown: boolean;
238
  enum: boolean;
239
  enumValues: boolean;
240
  dedupeEnums: boolean;
241
  excludeDeprecated: boolean;
242
  exportType: boolean;
243
  immutable: boolean;
244
  rootTypes: boolean;
245
  rootTypesNoSchemaPrefix: boolean;
246
  pathParamsAsTypes: boolean;
247
  propertiesRequiredByDefault: boolean;
248
  makePathsEnum: boolean;
249
  generatePathParams: boolean;
250
  silent: boolean;
251
  resolve(ref: string): any;
252
}
253

254
interface TransformNodeOptions {
255
  path: string;
256
  ctx: GlobalContext;
257
  schema: OpenAPI3;
258
}
259
```