Hey API — Generate Production-Ready SDKs from OpenAPI Specs

Introduction

Hey API is an open-source code generation tool that transforms OpenAPI and Swagger specifications into type-safe client SDKs. It produces clean, human-readable TypeScript or Python code with full type safety, eliminating the boilerplate of manually writing API clients.

What Hey API Does

• Generates fully typed API client code from OpenAPI 2.0, 3.0, and 3.1 specifications
• Produces runtime validators using Zod, Valibot, or Arktype from API schemas
• Creates mock data generators for testing based on API response schemas
• Supports multiple HTTP clients including Fetch, Axios, and custom adapters
• Offers a plugin architecture for extending code generation behavior

Architecture Overview

Hey API processes OpenAPI specification files through a multi-stage pipeline: parsing, intermediate representation, and code generation. The core parser normalizes different OpenAPI versions into a unified IR. Plugins then operate on this IR to produce client code, validators, types, or mocks. The output is tree-shakeable, so bundlers only include the endpoints your code actually uses.

Self-Hosting & Configuration

• Install @hey-api/openapi-ts as a dev dependency in your project
• Point the CLI at a local file or remote URL for your OpenAPI spec
• Configure output directory and client library in hey-api.config.ts
• Select plugins for validators, mocks, or framework-specific integrations
• Run code generation as part of your build pipeline or CI

Key Features

• Clean, human-readable generated code that looks hand-written
• Tree-shakeable output for minimal bundle size
• Plugin system for Zod schemas, mock data, TanStack Query, and more
• Support for multiple HTTP client backends
• Active maintenance with millions of weekly npm downloads

Comparison with Similar Tools

• openapi-generator — supports many languages but produces verbose, hard-to-read code
• openapi-typescript — types-only, no runtime client or validators
• Orval — generates React Query hooks but less flexible plugin system
• swagger-codegen — the original generator, now legacy and less maintained
• Kiota — Microsoft's generator, focused on Graph API patterns

FAQ

Q: Which OpenAPI versions does Hey API support? A: It supports OpenAPI 2.0 (Swagger), 3.0, and 3.1 specifications.

Q: Can I use Hey API with a non-TypeScript project? A: Hey API primarily targets TypeScript. Python support is available through community plugins. Other languages should use openapi-generator.

Q: How do I keep generated code up to date? A: Run the CLI as a build step or CI job. When your OpenAPI spec changes, re-run generation and commit the updated client code.

Q: Does Hey API support authentication? A: Yes. It generates typed auth configuration based on the security schemes defined in your OpenAPI spec.

Sources

• https://github.com/hey-api/hey-api
• https://heyapi.dev