{"id":11477,"library":"oazapfts","title":"oazapfts OpenAPI TypeScript Client Generator","description":"oazapfts is a specialized tool for generating TypeScript API clients directly from OpenAPI or Swagger specifications. Unlike template-based generators, it leverages TypeScript's Abstract Syntax Tree (AST) API, resulting in faster code generation and highly optimized, tree-shakeable client libraries. The current stable version is 7.5.0, with frequent alpha and minor releases demonstrating active development. Key differentiators include its AST-driven approach, which avoids HTTP-specific implementation details in method signatures, grouping all optional parameters into a single object for improved ergonomics. Generated clients are self-contained in a single file and provide individually exported functions, promoting efficient tree-shaking for modern bundlers. It is primarily consumed via a command-line interface but also exposes a programmatic generation API.","status":"active","version":"7.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/oazapfts/oazapfts","tags":["javascript","openapi","typescript","codegen","oazapfts"],"install":[{"cmd":"npm install oazapfts","lang":"bash","label":"npm"},{"cmd":"yarn add oazapfts","lang":"bash","label":"yarn"},{"cmd":"pnpm add oazapfts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for the generated client code to function at runtime, providing core fetch logic and utilities.","package":"@oazapfts/runtime","optional":false}],"imports":[{"note":"For tree-shaking efficiency and clarity, prefer named imports for individual API operations. The generated file exports functions directly, not a default object.","wrong":"import api from './my-generated-api';\nconst res = api.getPetById(1);","symbol":"getPetById","correct":"import { getPetById } from './my-generated-api';"},{"note":"This pattern imports all generated API functions under a namespace. While functional, it's less ideal for tree-shaking compared to individual named imports. Generated clients are ESM-first.","wrong":"const api = require('./my-generated-api');","symbol":"api","correct":"import * as api from './my-generated-api';"},{"note":"The programmatic `generate` function is exposed via a subpath import, specifically `oazapfts/generate`, and was stabilized in v7.5.0. Direct import from 'oazapfts' is for the CLI entry point, not programmatic use.","wrong":"import { generate } from 'oazapfts';","symbol":"generate","correct":"import { generate } from 'oazapfts/generate';"},{"note":"Types like `RequestOpts` are part of the `@oazapfts/runtime` package, which is a peer dependency that needs to be explicitly installed. Use a type-only import for clarity.","wrong":"import { RequestOpts } from 'oazapfts';","symbol":"RequestOpts","correct":"import type { RequestOpts } from '@oazapfts/runtime';"}],"quickstart":{"code":"import { mkdir, writeFile } from 'node:fs/promises';\nimport { generate } from 'oazapfts/generate';\n\n// A minimal OpenAPI spec for demonstration\nconst openApiSpec = {\n  openapi: '3.0.0',\n  info: { title: 'Test API', version: '1.0.0' },\n  paths: {\n    '/items': {\n      get: {\n        operationId: 'getItems',\n        summary: 'Retrieve a list of items',\n        responses: { '200': { description: 'A list of items', content: { 'application/json': { schema: { type: 'array', items: { type: 'string' } } } } } }\n      },\n      post: {\n        operationId: 'createItem',\n        summary: 'Create a new item',\n        requestBody: {\n          required: true,\n          content: { 'application/json': { schema: { type: 'object', properties: { name: { type: 'string' } } } } }\n        },\n        responses: { '201': { description: 'Item created' } }\n      }\n    }\n  }\n};\n\nasync function main() {\n  const outputDir = './generated-client';\n  await mkdir(outputDir, { recursive: true });\n  const outputPath = `${outputDir}/api.ts`;\n\n  // Generate the client code\n  const clientCode = await generate({\n    spec: openApiSpec,\n    url: 'https://example.com/api-docs',\n    plugins: [] // You can add custom plugins here\n  });\n\n  await writeFile(outputPath, clientCode);\n  console.log(`OpenAPI client generated to ${outputPath}`);\n\n  // Example of consuming the generated API (conceptually)\n  console.log('\\n// To use the generated client (after installing @oazapfts/runtime):');\n  console.log(`// import { getItems, createItem } from './generated-client/api';`);\n  console.log(`// import { fetch } from '@oazapfts/runtime';`);\n  console.log(`// const items = await getItems();`);\n  console.log(`// await createItem({ name: 'New Item' });`);\n}\n\nmain().catch(console.error);\n","lang":"typescript","description":"This quickstart demonstrates programmatically generating a TypeScript API client from a mock OpenAPI specification and outlines how to consume the generated functions with named imports, highlighting the necessary runtime dependency."},"warnings":[{"fix":"Ensure `oazapfts` is installed as a production dependency in your project: `npm install oazapfts` or `yarn add oazapfts`.","message":"With version 3.0.0, oazapfts transitioned from embedding all fetch logic directly into the generated code to becoming a runtime dependency. This means generated clients now rely on `oazapfts` to be available in the runtime environment.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install the runtime package alongside oazapfts: `npm install @oazapfts/runtime` or `yarn add @oazapfts/runtime`. Ensure its version is compatible with your `oazapfts` installation.","message":"As of version 6.0.0, the core runtime logic for oazapfts was extracted into a separate peer dependency, `@oazapfts/runtime`. Generated client code depends on this package for its fetching capabilities.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Begin using the `--futureStripLegacyMethods` flag explicitly during generation and update your client code to use the normalized `operationId`-based method names. This prepares your codebase for the next breaking change.","message":"The `--futureStripLegacyMethods` CLI option, introduced to remove deprecated HTTP verb/path-based aliases for operation IDs containing special characters, will become the default behavior in a future major version. Relying on legacy method names is discouraged.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Always install `oazapfts` and `@oazapfts/runtime` together and ensure their versions are compatible, ideally using exact versions or carefully managed range constraints specified by `oazapfts` itself.","message":"When using `npm` with `oazapfts`, be mindful of `@oazapfts/*` internal package version ranges (e.g., between `oazapfts` and `@oazapfts/runtime`). Mismatched versions can lead to unexpected behavior or build errors.","severity":"gotcha","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the runtime dependency: `npm install @oazapfts/runtime` or `yarn add @oazapfts/runtime`.","cause":"The `@oazapfts/runtime` package, which provides the necessary fetch utilities for generated clients, has not been installed.","error":"Error: Cannot find module '@oazapfts/runtime'"},{"fix":"Ensure your project is configured for ES modules or that your bundler correctly handles named exports. Verify that you are using named imports like `import { getPetById } from './my-generated-api';` instead of default imports or `require`.","cause":"This typically occurs in a CommonJS environment or when bundlers incorrectly resolve ESM named exports, or when a default import is attempted for a file that only provides named exports.","error":"TypeError: (0, _my_generated_api_ts__WEBPACK_IMPORTED_MODULE_0__.getPetById) is not a function"},{"fix":"Provide a correct path to a local JSON/YAML spec file, a URL to a remote spec, or pass a valid OpenAPI object directly to the `generate` function.","cause":"The `oazapfts` CLI or programmatic `generate` function was invoked without a valid OpenAPI/Swagger specification path or URL.","error":"Invalid `spec` argument: must be a URL or a path to a local OpenAPI/Swagger spec file."}],"ecosystem":"npm"}