openapi-types

openapi-types provides a complete set of TypeScript interfaces and namespaces (OpenAPI, OpenAPIV2, OpenAPIV3, OpenAPIV3_1) that mirror the structure of the OpenAPI and Swagger specifications. It types every part of a document — info blocks, paths, operations, parameters, schemas, security requirements, and components — so tools that read or generate OpenAPI documents get compile-time safety without writing their own type layer.

Maintained as one package inside the kogosoftwarellc/open-api monorepo (alongside express-openapi and related tooling), it has become the de facto standard for typing OpenAPI documents in the Node/TypeScript ecosystem, pulling in tens of millions of weekly downloads.

What You Get

• Version-specific namespaces — OpenAPIV2, OpenAPIV3, and OpenAPIV3_1 each fully model their respective specification version
• A version-agnostic OpenAPI namespace with union types (Document, Operation, Parameter) for code that needs to handle any spec version
• Complete coverage of specification objects — paths, operations, parameters, schemas, responses, security schemes, servers, and components
• Zero runtime footprint — pure type declarations with no bundled JavaScript logic to execute or maintain

Common Use Cases

• Typing the input/output of OpenAPI parsers and validators (e.g. swagger-parser, express-openapi) so consumers get IntelliSense on spec documents
• Building code generators that read an OpenAPI document and emit clients, servers, or mock data
• Writing custom middleware that inspects request-scoped OpenAPI metadata (route, operation, schema) in a type-safe way
• Authoring or transforming OpenAPI documents programmatically instead of by hand-editing YAML/JSON

Under The Hood

Architecture The entire package is a single 918-line index.ts organized into four namespaces: OpenAPIV2, OpenAPIV3, and OpenAPIV3_1 each independently model one specification version’s object graph, while the top-level OpenAPI namespace layers version-spanning union types (Document, Operation, Parameter) over the other three. Rather than redefining every OpenAPIV3_1 type from scratch, the 3.1 namespace builds on the 3.0 namespace through Modify/Omit/Pick mapped-type transformations, expressing only what changed between spec versions — a deliberate reuse pattern that keeps the three version namespaces from drifting apart. There is no other source layout to speak of: tsconfig.json restricts compilation to this one file, and the shared bin/tsc wrapper (used by every package in the monorepo) compiles it to a declaration-only dist/ output.

Tech Stack The package has zero runtime dependencies — package.json declares none — and is built with TypeScript 4.7.2 in strict mode via the monorepo’s shared bin/tsc wrapper, targeting CommonJS with declaration and source-map output enabled. It is one workspace inside a Lerna-orchestrated monorepo (kogosoftwarellc/open-api) alongside sibling packages like express-openapi and koa-openapi, and is published independently to npm through lerna publish.

Code Quality No test files exist for this package specifically — correctness rests entirely on the TypeScript compiler’s strict-mode checking rather than on unit tests, which is a meaningfully weaker guarantee for a types-only package since there’s no way to assert at build time that a given type actually matches real-world OpenAPI documents. The monorepo does wire up mocha/chai/nyc/istanbul and tslint+prettier repo-wide for its runtime packages, but that tooling isn’t exercised against openapi-types itself. Naming is consistent throughout, mirroring the official OpenAPI specification vocabulary object-for-object (ParameterObject, SchemaObject, ComponentsObject), which makes the types easy to cross-reference against the spec.

API Design The split between version-specific namespaces and a version-agnostic union namespace is a considered design choice: consumers who know they’re working with one spec version get precise types (OpenAPIV3.Document), while consumers that must accept any version get OpenAPI.Document without extra runtime cost. A generic parameter on Document<T> lets consumers type vendor extensions (like x-amazon-apigateway-integration) instead of losing type safety on custom fields. Adoption requires zero boilerplate — a single named import — though the pattern itself (a types-only package mirroring an external spec) is standard practice rather than a novel approach.