@samveys/openapi — Dokumentasi

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

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

Command	Does
`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

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.

#Use it

#Commands

#The generated client

Use it

Commands

The generated client