HOW-TO · DEV

How to build a type-safe API client using an AI assistant that reads your OpenAPI spec

advanced30 minBy Fredoline Eruo
Target environment
Ubuntu 24.04 · Ollama 0.4.x
PREREQUISITES

OpenAPI 3.x specification for the target API, Node.js 18+, TypeScript 5+, AI API access (OpenAI or Anthropic)

What this does

OpenAPI specifications describe REST endpoints, request bodies, response schemas, and authentication methods in YAML or JSON format. This guide explains how to feed an OpenAPI spec to an AI assistant and request generation of a fully typed TypeScript API client. The output includes TypeScript interfaces for all request parameters and response bodies, typed fetch wrappers for each endpoint, and authentication middleware — all aligned with the spec without manual translation.

Steps

  1. Validate the OpenAPI spec using swagger-cli or redocly to confirm it parses without errors before passing it to the AI.
  2. Split large specs (over 2,000 lines) into logical sections: paths, components/schemas, and components/securitySchemes. Process one section at a time to avoid token limits.
  3. Construct a prompt that includes the spec section, instructions for generating TypeScript interfaces, a fetch-based client class, and a request helper that infers types from the path and method.
  4. Request the AI to generate a single TypeScript source file per spec section. Require strict mode (strict: true) in the generated tsconfig output.
  5. Assemble the generated files into a client package. Add a top-level ApiClient class that exposes named methods for each endpoint.
  6. Run tsc --noEmit to confirm type correctness. Address any any type annotations the AI introduced by feeding the error back with a refinement prompt.
  7. Export the client package with package.json, tsconfig.json, and a README that links generated types to OpenAPI operation IDs.

Verification

# Verify TypeScript compiles with strict mode and no errors
npx tsc --noEmit --strict --target ES2020 --moduleResolution node src/index.ts 2>&1
echo "TypeScript compilation exit code: $?"
# Expected: TypeScript compilation exit code: 0

Common failures

  • OpenAPI spec uses $ref circularly or contains broken references. Pre-process the spec with swagger-cli dereference to flatten all $ref nodes before sending to the AI.
  • Generated types use loose any instead of precise unions. Pass the TypeScript compiler errors back to the AI as a refinement prompt with the instruction "replace any with the exact union type from the OpenAPI schema."
  • Spec is too large for a single AI context window. Chunk the spec by tag or by path prefix and generate separate source files for each chunk, then merge with type-compatible imports.
  • Authentication helpers generated are incorrect for the security scheme. Verify the security array in the spec and confirm the AI selected the correct header or bearer token pattern.
  • Version mismatch - The installed package or runtime differs from the command shown; check the version first and rerun the smallest verification command.
  • Local environment drift - Another service, virtual environment, model, or path is being used; print the active binary path and configuration before changing the guide steps.

Related guides

n

← All how-to guidesCourses →