to-openapi

Generate OpenAPI 3.1 specs from any TypeScript schema library — Zod, ArkType, Valibot, and more.

Features

• Schema-agnostic — Works with any library that implements Standard Schema (Zod, ArkType, Valibot, etc.)
• Two APIs — Declarative openapi() function or chainable OpenAPI class builder
• Plugin system — Transform routes, schemas, and documents with composable plugins
• Spec merging — Combine multiple OpenAPI documents with merge() for microservices
• Type-safe — Full TypeScript support with exported types for every concept

Install

npm install to-openapi

Quick Start

Declarative API

import { openapi } from 'to-openapi'

const spec = openapi({
  info: { title: 'My API', version: '1.0.0' },
  paths: {
    'GET /users': {
      200: UserSchema,
    },
    'POST /users': {
      body: CreateUserSchema,
      201: UserSchema,
    },
    'GET /users/:id': {
      200: UserSchema,
      404: null,
    },
  },
})

Class Builder API

import { OpenAPI } from 'to-openapi'

const spec = new OpenAPI({
  info: { title: 'My API', version: '1.0.0' },
})
  .schema('User', UserSchema)
  .route('get', '/users', {
    200: UserSchema,
  })
  .route('post', '/users', {
    body: CreateUserSchema,
    201: UserSchema,
  })
  .route('get', '/users/{id}', {
    200: UserSchema,
    404: null,
  })
  .document()

Both produce a fully valid OpenAPI 3.1.0 document with schemas automatically extracted to components/schemas and referenced via $ref.

Documentation

Visit the documentation site for the full guide, API reference, framework integrations, plugin authoring, and examples.

• Why to-openapi?
• Getting Started
• API Reference
• Plugins
• Examples

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

License

MIT