1. Docs
  2. Packages

@samveys/openapi

Version
1.0.2Nov 5, 2026
Install
pnpm add @samveys/openapi

From packages/openapi/README.md in the framework repository.

An OpenAPI 3.1 document built from the route schemas you already have, a typed client generator, and a check that a release does not break clients.

Use it

ts
import { createApp } from '@samveys/core'
import { http } from '@samveys/http'
import { openapi } from '@samveys/openapi'

export const app = createApp({
  name: 'billing',
  plugins: [http(), openapi({ title: 'Billing API', version: '1.4.0' })],
})
  • /docs and /docs/openapi.json are served only when the app runs in local, unless serveInProduction: true.
  • Parameters come from params and query schemas, bodies from body, responses from response, plus RFC 9457 problem responses (422 for validation, default for errors).
  • Validator schemas are described with toJsonSchema() from @samveys/validator. Custom refine() checks and transform()s cannot be expressed and are left out.

Commands

CommandDoes
svs generate:openapi [--out openapi.json]Writes the document
svs generate:client [--out client.ts]Writes a fetch client with precomputed types (plain interfaces, no inference at edit time)
svs openapi:diff --base released.json [--head new.json]Lists changes; exits 1 with SVS_E117 when a change breaks clients and the major version did not increase

Breaking rules: a removed operation, response field or enum value, a response field that may now be missing, a new required request field or parameter, and a narrowed request type or widened response type. Added operations and optional fields are not breaking.

The generated client

ts
import { createClient } from './client.ts'

const api = createClient({ baseUrl: 'https://billing.internal' })
const invoice = await api.invoicesShow({ id: 42 }) // typed response; a wrong field is a tsc error

Errors throw ApiError with the status and the RFC 9457 problem.