Generate from OpenAPI

Use @hulla/api-openapi when another team or service owns an OpenAPI document and the application needs a typed @hulla/api contract without translating every path, input, and response by hand.

The import creates two TypeScript files:

• src/api.generated.ts contains the executable runtime contract and generated Zod schemas.
• src/api.generated.openapi.ts contains the typed documentation sidecar.

Treat the OpenAPI document as the source of truth. Change the document, then regenerate the contract and sidecar.

The default generator writes Zod schemas, so install Zod with @hulla/api and the OpenAPI package.

bun add @hulla/api @hulla/api-openapi zod

npm install @hulla/api @hulla/api-openapi zod

pnpm add @hulla/api @hulla/api-openapi zod

yarn add @hulla/api @hulla/api-openapi zod

Save this provider-owned description as openapi.yaml:

openapi: 3.1.2
info:
  title: Pets API
  version: 1.0.0
paths:
  /pets/{id}:
    get:
      operationId: getPet
      parameters:
        - name: id
          in: path
          required: true
          description: Pet identifier
          schema:
            type: string
      responses:
        '200':
          description: Pet found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '404':
          description: Pet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Pet:
      type: object
      additionalProperties: false
      required: [id, name]
      properties:
        id: { type: string }
        name: { type: string }
    Problem:
      type: object
      additionalProperties: false
      required: [message]
      properties:
        message: { type: string }

Bundle external references before importing. The importer resolves references inside the document, primarily #/components/schemas/...; it does not fetch remote files or URLs.

Run the import from the project root:

hulla-openapi import ./openapi.yaml \
  --contract ./src/api.generated.ts \
  --openapi ./src/api.generated.openapi.ts

The command creates parent directories and replaces both targets. {id} becomes the contract path parameter :id, and operationId: getPet becomes the route key getPet.

The generated runtime contract has this shape, formatted here for readability:

import { defineContract, response, route } from '@hulla/api'
import { z } from 'zod'

const PetSchema = z
  .object({
    id: z.string(),
    name: z.string(),
  })
  .strict()

const ProblemSchema = z
  .object({
    message: z.string(),
  })
  .strict()

export const contract = defineContract({
  routes: {
    getPet: route.get('/pets/:id', {
      params: z.object({ id: z.string() }),
      responses: {
        200: response.json(PetSchema, { contentType: 'application/json' }),
        404: response.json(ProblemSchema, { contentType: 'application/json' }),
      },
    }),
  },
})

The generated sidecar preserves the OpenAPI descriptions separately from runtime behavior. The actual file also retains the top-level components object from the source document.

import { defineOpenAPI } from '@hulla/api-openapi'
import { contract } from './api.generated'

export default defineOpenAPI(contract, {
  openapi: '3.1.2',
  info: { title: 'Pets API', version: '1.0.0' },
  routes: {
    getPet: {
      operationId: 'getPet',
      request: {
        path: { id: { description: 'Pet identifier' } },
      },
      responses: {
        200: { description: 'Pet found' },
        404: { description: 'Pet not found' },
      },
    },
  },
})

The application imports contract from api.generated.ts. The sidecar is used by OpenAPI generation and does not create a second client runtime.

Use the generated contract with the same client and transport APIs as a hand-written contract:

import { createClient } from '@hulla/api/client'
import { fetchTransport } from '@hulla/api/fetch'
import { contract } from './api.generated'

const client = createClient(contract, {
  transport: fetchTransport({
    baseUrl: 'https://api.example.com',
  }),
})

const result = await client.getPet({
  params: { id: 'pet-123' },
})

if (result.status === 200) {
  console.log(result.body.name)
} else {
  console.error(result.body.message)
}

Declared 4xx and 5xx responses remain status-discriminated data. Network failures, malformed JSON, content-type mismatches, statuses absent from the contract, and codec decoding failures reject the client call. Ordinary response schemas describe types but are not re-run by the client against otherwise valid JSON.

Commit both generated files when the application relies on them, then check them in CI:

hulla-openapi check ./openapi.yaml \
  --contract ./src/api.generated.ts \
  --openapi ./src/api.generated.openapi.ts

check regenerates both files in memory and compares their exact contents. It exits unsuccessfully when either file is missing or differs, and it does not modify the files.

The comparison is byte-for-byte. Exclude these generated files from formatters, or run hulla-openapi import after formatting, so a formatting-only rewrite does not fail the drift check.

The default zodSchemaCodeGenerator() converts the HTTP wire schema, not application-side codecs or their encode/decode functions.

The default generator covers JSON objects, arrays, strings, numbers, integers, booleans, null, enums, constants, unions, intersections, nullability, common string formats, bounds, required, and additionalProperties. Less common constraints such as minItems, maxItems, multipleOf, patternProperties, $defs, and unevaluatedProperties are not preserved by the default generator. Inspect the generated code when the source document depends on those keywords.

Component names must produce unique TypeScript identifiers. Generation rejects names that begin with a number and collisions such as User-ID and User_ID; rename the components and their references before importing.

OpenAPI 3.0 input produces a warning and a generated 3.1.2 sidecar. Only an input whose version is exactly 3.2.0 keeps 3.2.0. If a document uses the query operation, make the source OpenAPI 3.2.0 so the generated sidecar can be exported again; OpenAPI 3.1 cannot represent HTTP QUERY.

Use the public functions when a build tool needs generated strings or must inspect non-fatal diagnostics:

import {
  generateContractFromOpenAPI,
  readOpenAPIDocument,
  writeGeneratedOpenAPIContract,
} from '@hulla/api-openapi'

const document = await readOpenAPIDocument('./openapi.yaml')
const generated = generateContractFromOpenAPI(document, {
  contractImport: './api.generated',
})

for (const diagnostic of generated.diagnostics) {
  console.warn(diagnostic.location, diagnostic.message)
}

await writeGeneratedOpenAPIContract(generated, {
  contract: './src/api.generated.ts',
  openapi: './src/api.generated.openapi.ts',
})

generateContractFromOpenAPI() throws OpenAPIImportError when structured diagnostics include an error. Some malformed documents and unresolved references can also throw ordinary errors. The CLI stops on errors but does not print non-fatal warnings; use the programmatic diagnostics array when warnings must be reviewed or enforced.

The optional schemaGenerator setting accepts an OpenAPISchemaCodeGenerator implementation when the generated contract must use another schema library or mapping. That implementation owns imports, component declarations, schema conversion, and object generation.

For the code-first direction, continue to exporting a contract. For client error behavior, see errors.