@openapi-spec/types provides TypeScript types for the OpenAPI Specification, covering versions 3.0, 3.1, and 3.2. Every object and field is modelled after the specification, and every field carries the specification's own description as JSDoc with a link to its section, so the spec is readable from your editor. The package ships types only, no runtime code.

Each version module targets the latest patch release of its minor line:

| Module | Specification | Notes | | -------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | @openapi-spec/types/v3.0 | OpenAPI 3.0.4 | | | @openapi-spec/types/v3.1 | OpenAPI 3.1.2 | Reuses 3.0 types for objects that did not change or only gained fields | | @openapi-spec/types/v3.2 | OpenAPI 3.2.1 | Reuses 3.1 types for objects that did not change or only gained fields |

Usage

// A whole version as a namespace, handy when mixing versions in one file
import type * as OpenAPIV3_0 from '@openapi-spec/types/v3.0'
// Or the types of one version directly
import type { OpenAPIObject, SchemaObject } from '@openapi-spec/types/v3.1'

const doc: OpenAPIObject = {
  openapi: '3.1.2',
  info: { title: 'Pet Store', version: '1.0.0' },
  paths: {},
}

// SchemaObject takes an optional data type for its data-carrying fields:
// `enum`, `default`, `example`, and from 3.1 on `const` and `examples`
const status = {
  type: 'string',
  enum: ['available', 'pending', 'sold'],
  default: 'available',
} satisfies SchemaObject<string>

Conventions

• Type names follow the specification's section names: InfoObject, PathItemObject, SchemaObject, and so on.
• Fields the specification marks as deprecated carry an @deprecated tag.
• Rules the type system can express are enforced: allowed fields, value shapes, and version-specific literals such as style values. Rules it cannot express, like mutually exclusive fields or "at least one of", are stated in the JSDoc instead.

The types are checked against the official example documents and the specification's own schema test corpus. See tests/README.md.

Sponsors

Like what we build over at middleapi? You can help keep it going through GitHub Sponsors or Open Collective. Every bit helps! 🚀

Organization Sponsors

Sponsors

Backers

With thanks to 40 past sponsors who helped get openapi-spec here.

Open Source Programs

middleapi is supported by these open source programs:

License

Distributed under the MIT License. See LICENSE for more information.