@contractkit/openapi-to-ck

@contractkit/openapi-to-ck

Convert OpenAPI specs (2.0, 3.0, 3.1) into ContractKit .ck files. Useful for adopting ContractKit in projects that already have an OpenAPI document, or for round-tripping a spec through CK.

Installation

pnpm add -D @contractkit/openapi-to-ck

Use as a CLI subcommand

When the package is installed, the @contractkit/cli binary picks up an openapi-to-ck subcommand:

contractkit openapi-to-ck --input openapi.yaml --output contracts/

Flag	Description
--input <path>	Path to an OpenAPI YAML or JSON file.
--output <dir>	Directory to write .ck files into.
--split <single | by-tag>	Output mode. by-tag (default) writes one file per OpenAPI tag; single writes one combined file.
--no-comments	Don't emit OpenAPI descriptions as # comments.

Programmatic use

import { convertOpenApiToCk } from '@contractkit/openapi-to-ck';

const { files, warnings } = await convertOpenApiToCk({
    input: 'openapi.yaml',          // file path, JSON/YAML string, or pre-parsed object
    split: 'by-tag',                // 'single' | 'by-tag'  (default: 'by-tag')
    includeComments: true,          // emit OpenAPI descriptions as # comments (default: true)
    onWarning: w => console.warn(w),
});

// `files` is a Map<filename, ckSource>
for (const [filename, source] of files) {
    await fs.writeFile(filename, source);
}

Warning entries carry a JSON-pointer-style path into the OpenAPI spec, a human-readable message, and a severity of 'info' | 'warn'.

What's converted

OpenAPI	.ck
paths	operation /path: { ... } blocks
components.schemas	contract Name: { ... } declarations
parameters (path / query / header)	params: { ... } / query: { ... } / headers: { ... } blocks
requestBody.content[mime].schema	request: { mime: Type }
responses[code].content[mime].schema	response: { code: { mime: Type } }
responses[code].headers	per-status headers: { name: type }
allOf	& intersection on contract declarations
oneOf + discriminator	discriminated(by=field, A | B)
oneOf / anyOf (no discriminator)	| union
enum, pattern, minimum/maximum, minLength/maxLength	type constraint args

Other exports

For tools that want to operate on the intermediate AST rather than emit .ck source:

import {
    schemasToModels,        // OpenAPI schemas → ContractKit ModelNode[]
    pathsToRoutes,          // OpenAPI paths   → ContractKit OpRouteNode[]
    splitByTag,             // group routes by OpenAPI tag
    mergeIntoSingle,        // collapse roots into one
    detectCircularRefs,     // find $ref cycles
    extractRefName,         // "#/components/schemas/Foo" → "Foo"
    sanitizeName,           // turn an arbitrary string into a valid CK identifier
    normalize,              // upgrade 2.0/3.0 → 3.1 + dereference
    astToCk,                // ContractKit AST → `.ck` source string
    serializeType,          // ContractTypeNode → `.ck` type expression
} from '@contractkit/openapi-to-ck';