0
# OpenAPI3-TS
1

2
OpenAPI3-TS is a comprehensive TypeScript library providing typed models and utilities for building OpenAPI 3.x specification documents. It offers complete support for both OpenAPI 3.0 and 3.1 specifications with a fluent DSL builder pattern, enabling type-safe programmatic creation of OpenAPI contracts from scratch.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { oas30, oas31, Server, ServerVariable } from "openapi3-ts";
15
```
16

17
For version-specific imports:
18

19
```typescript
20
import { OpenApiBuilder } from "openapi3-ts/oas30";
21
import { OpenApiBuilder } from "openapi3-ts/oas31";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { oas30, oas31, Server, ServerVariable } = require("openapi3-ts");
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { oas30 } from "openapi3-ts";
34

35
// Create a new OpenAPI 3.0 document
36
const builder = oas30.OpenApiBuilder.create()
37
  .addTitle("Pet Store API")
38
  .addVersion("1.0.0")
39
  .addDescription("A sample API for managing pets")
40
  .addPath("/pets", {
41
    get: {
42
      summary: "List all pets",
43
      responses: {
44
        "200": {
45
          description: "A list of pets",
46
          content: {
47
            "application/json": {
48
              schema: {
49
                type: "array",
50
                items: { $ref: "#/components/schemas/Pet" }
51
              }
52
            }
53
          }
54
        }
55
      }
56
    }
57
  })
58
  .addSchema("Pet", {
59
    type: "object",
60
    required: ["id", "name"],
61
    properties: {
62
      id: { type: "integer", format: "int64" },
63
      name: { type: "string" },
64
      tag: { type: "string" }
65
    }
66
  });
67

68
// Export as JSON or YAML
69
const spec = builder.getSpec();
70
const json = builder.getSpecAsJson(null, 2);
71
const yaml = builder.getSpecAsYaml();
72
```
73

74
## Architecture
75

76
OpenAPI3-TS is built around several key components:
77

78
- **Dual OpenAPI Support**: Separate namespaces (`oas30`, `oas31`) with complete OpenAPI 3.0 and 3.1 specification coverage
79
- **Fluent Builder Pattern**: `OpenApiBuilder` class providing chainable method calls for programmatic document construction
80
- **Type Safety**: Comprehensive TypeScript interfaces covering all OpenAPI specification components
81
- **Extension Support**: Full support for OpenAPI specification extensions (`x-*` properties)
82
- **Multi-Format Export**: Built-in JSON and YAML serialization capabilities
83
- **Zero Dependencies**: Only requires `yaml` for YAML processing, no other external dependencies
84

85
## Capabilities
86

87
### OpenAPI 3.0 Builder
88

89
Fluent DSL for creating OpenAPI 3.0 specification documents with complete type safety and chainable operations.
90

91
```typescript { .api }
92
class OpenApiBuilder {
93
  static create(doc?: oas30.OpenAPIObject): OpenApiBuilder;
94
  getSpec(): oas30.OpenAPIObject;
95
  getSpecAsJson(replacer?: (key: string, value: unknown) => unknown, space?: string | number): string;
96
  getSpecAsYaml(replacer?: Parameters<typeof yaml.stringify>[1], options?: Parameters<typeof yaml.stringify>[2]): string;
97
}
98
```
99

100
[OpenAPI 3.0 Builder](./openapi30-builder.md)
101

102
### OpenAPI 3.1 Builder
103

104
Fluent DSL for creating OpenAPI 3.1 specification documents with enhanced JSON Schema support and webhook capabilities.
105

106
```typescript { .api }
107
class OpenApiBuilder {
108
  static create(doc?: oas31.OpenAPIObject): OpenApiBuilder;
109
  addWebhook(webhook: string, webhookItem: oas31.PathItemObject): OpenApiBuilder;
110
}
111
```
112

113
[OpenAPI 3.1 Builder](./openapi31-builder.md)
114

115
### OpenAPI 3.0 Type System
116

117
Complete TypeScript interfaces for all OpenAPI 3.0 specification components including schemas, operations, and security.
118

119
```typescript { .api }
120
interface OpenAPIObject extends ISpecificationExtension {
121
  openapi: string;
122
  info: InfoObject;
123
  servers?: ServerObject[];
124
  paths: PathsObject;
125
  components?: ComponentsObject;
126
  security?: SecurityRequirementObject[];
127
  tags?: TagObject[];
128
  externalDocs?: ExternalDocumentationObject;
129
}
130
```
131

132
[OpenAPI 3.0 Types](./openapi30-types.md)
133

134
### OpenAPI 3.1 Type System
135

136
Enhanced TypeScript interfaces for OpenAPI 3.1 with JSON Schema Draft 2020-12 support and webhook definitions.
137

138
```typescript { .api }
139
interface OpenAPIObject extends ISpecificationExtension {
140
  openapi: string;
141
  info: InfoObject;
142
  servers?: ServerObject[];
143
  paths?: PathsObject;
144
  components?: ComponentsObject;
145
  security?: SecurityRequirementObject[];
146
  tags?: TagObject[];
147
  externalDocs?: ExternalDocumentationObject;
148
  webhooks?: PathsObject;
149
}
150
```
151

152
[OpenAPI 3.1 Types](./openapi31-types.md)
153

154
### Server Management
155

156
Classes for defining and managing OpenAPI server configurations with variable support and extension capabilities.
157

158
```typescript { .api }
159
class Server implements ServerObject {
160
  constructor(url: string, desc?: string);
161
  addVariable(name: string, variable: ServerVariable): void;
162
  url: string;
163
  description?: string;
164
  variables: { [v: string]: ServerVariable };
165
}
166

167
class ServerVariable implements ServerVariableObject {
168
  constructor(defaultValue: string | boolean | number, enums?: string[] | boolean[] | number[], description?: string);
169
  enum?: string[] | boolean[] | number[];
170
  default: string | boolean | number;
171
  description?: string;
172
}
173
```
174

175
[Server Management](./server-management.md)
176

177
### Specification Extensions
178

179
Support for OpenAPI specification extensions (`x-*` properties) with validation and management utilities.
180

181
```typescript { .api }
182
type IExtensionName = `x-${string}`;
183
type IExtensionType = any;
184

185
interface ISpecificationExtension {
186
  [extensionName: IExtensionName]: IExtensionType;
187
}
188

189
class SpecificationExtension implements ISpecificationExtension {
190
  static isValidExtension(extensionName: string): boolean;
191
  getExtension(extensionName: string): any;
192
  addExtension(extensionName: string, payload: any): void;
193
  listExtensions(): string[];
194
}
195
```
196

197
[Specification Extensions](./specification-extensions.md)
198

199
## Common Types
200

201
```typescript { .api }
202
interface InfoObject extends ISpecificationExtension {
203
  title: string;
204
  description?: string;
205
  termsOfService?: string;
206
  contact?: ContactObject;
207
  license?: LicenseObject;
208
  version: string;
209
}
210

211
interface ContactObject extends ISpecificationExtension {
212
  name?: string;
213
  url?: string;
214
  email?: string;
215
}
216

217
interface LicenseObject extends ISpecificationExtension {
218
  name: string;
219
  url?: string;
220
}
221

222
interface ServerObject extends ISpecificationExtension {
223
  url: string;
224
  description?: string;
225
  variables?: { [v: string]: ServerVariableObject };
226
}
227

228
interface ServerVariableObject extends ISpecificationExtension {
229
  enum?: string[] | boolean[] | number[];
230
  default: string | boolean | number;
231
  description?: string;
232
}
233

234
interface ReferenceObject {
235
  $ref: string;
236
}
237

238
interface ExternalDocumentationObject extends ISpecificationExtension {
239
  description?: string;
240
  url: string;
241
}
242
```