openapi3-ts

openapi3-ts gives TypeScript and JavaScript projects a fully typed way to construct OpenAPI 3.x documents instead of hand-writing JSON or YAML. It ships parallel, version-isolated implementations for OAS 3.0, 3.1, and 3.2 — each with its own typed interfaces (OpenAPIObject, PathsObject, SchemaObject, and the rest of the spec’s object model) plus a fluent OpenApiBuilder class for assembling a document call by call.

Because each OAS version is its own subpath export (openapi3-ts/oas30, /oas31, /oas32), consumers pull in only the version they target with no cross-version type bleed, and the compiler enforces that a document built against 3.1 rules can’t accidentally use a 3.0-only or 3.2-only field. The finished document can be emitted as JSON via getSpecAsJson() or as YAML via getSpecAsYaml() (backed by the yaml package), and it has no other runtime dependencies, so it runs equally well in Node, Deno, or the browser.

What You Get

• Separate typed model modules for OAS 3.0, 3.1, and 3.2, each mirroring the official specification’s object model (InfoObject, PathsObject, SchemaObject, ComponentsObject, etc.)
• A fluent OpenApiBuilder class per version with chainable addInfo(), addPath(), addSchema(), addResponse(), addParameter(), and similar methods
• Built-in serialization to JSON (getSpecAsJson()) and YAML (getSpecAsYaml()) directly off the assembled document
• Version-scoped subpath exports (openapi3-ts/oas30, openapi3-ts/oas31, openapi3-ts/oas32) so a project only imports the spec version it targets
• A shared Server/ServerVariable type export usable across all three OAS versions
• Runs anywhere — Node, Deno, or the browser — with a single runtime dependency (yaml)

Common Use Cases

• Generating an OpenAPI 3.x contract programmatically from route definitions or decorators instead of maintaining a hand-written YAML file
• Building internal tooling that needs to construct, mutate, or validate the shape of OpenAPI documents with compile-time type safety
• Migrating an API description between OAS versions (3.0 to 3.1 or 3.2) using version-specific typed models to catch incompatible fields at compile time
• Powering code generators or API gateways that assemble an OpenAPI document at build time and export it as JSON or YAML for downstream consumers

Under The Hood

Architecture The library is a straightforward layered structure: src/model holds pure TypeScript interface definitions mirroring the OpenAPI spec object-by-object (openapi30.ts, openapi31.ts, openapi32.ts, oas-common.ts, server.ts, specification-extension.ts), while src/dsl holds three parallel OpenApiBuilder classes (openapi-builder30.ts, -31.ts, -32.ts) that wrap a rootDoc instance of the matching version’s OpenAPIObject behind chainable addX() methods. Version-specific entry points (oas30.ts, oas31.ts, oas32.ts) re-export the matching model-plus-builder pair, and the root index.ts aggregates all three namespaces plus the shared Server/ServerVariable types. There is no shared abstraction across the three OAS versions beyond structural parallelism, so a change to the core document shape is replicated three times rather than centralized; data flow is entirely synchronous and in-memory, with builder methods mutating rootDoc before getSpecAsJson()/getSpecAsYaml() serialize it.

Tech Stack Written in TypeScript, compiled via Vite library mode plus tsc --emitDeclarationOnly for type declarations, and published as dual CommonJS/ESM output with a package.json exports map carrying per-version subpath exports. The only runtime dependency is the yaml package for YAML serialization. Development tooling includes ESLint with the flat-config typescript-eslint setup, Prettier for formatting, Vitest with @vitest/coverage-v8 for testing, and coveralls for CI coverage reporting. There is no runtime framework, database, or deployment target — it is a pure library published to npm for consumption by other TypeScript/JavaScript projects.

Code Quality Spec files sit alongside their implementation files across both the model and DSL layers, covering type-shape checks and full builder fluent-chain assertions using Vitest’s describe/it/expect. Error handling is minimal but explicit where it matters — addOpenApiVersion() validates its input against a version-pattern regex and throws a descriptive error on malformed input — while elsewhere the library leans on TypeScript’s type system rather than runtime validation, consistent with its role as a typed-contract builder rather than a validator. Naming is consistent fluent addX() builder methods throughout, and the codebase is strictly typed with only a single file-level eslint-disable for no-explicit-any in the model layer’s extension fields. CI runs lint, build, and test stages on every change.

API Design The most distinctive choice is maintaining three fully separate, parallel model-and-builder implementations for OAS 3.0, 3.1, and 3.2 rather than one merged superset type, so consumers import exactly the version-specific subpath they need with no cross-version type pollution — a level of discipline uncommon among spec-modeling libraries, most of which ship untyped or version-merged definitions. The fluent builder chain plus direct JSON/YAML serialization keeps boilerplate to a handful of chained calls with full editor autocomplete, and there is no setup or configuration step required to start building a document.