oazapfts OpenAPI TypeScript Client Generator

Common errors

• Error: Cannot find module '@oazapfts/runtime'

  cause The `@oazapfts/runtime` package, which provides the necessary fetch utilities for generated clients, has not been installed.
  fix Install the runtime dependency: `npm install @oazapfts/runtime` or `yarn add @oazapfts/runtime`.

• TypeError: (0, _my_generated_api_ts__WEBPACK_IMPORTED_MODULE_0__.getPetById) is not a function

  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.
  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`.

• Invalid `spec` argument: must be a URL or a path to a local OpenAPI/Swagger spec file.

  cause The `oazapfts` CLI or programmatic `generate` function was invoked without a valid OpenAPI/Swagger specification path or URL.
  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.

Warnings

• breaking 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.
  Fix: Ensure `oazapfts` is installed as a production dependency in your project: `npm install oazapfts` or `yarn add oazapfts`.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install oazapfts npm
• yarn add oazapfts yarn
• pnpm add oazapfts pnpm

Imports

• getPetById
  wrong:

  import api from './my-generated-api';
  const res = api.getPetById(1);

  correct:

  import { getPetById } from './my-generated-api';

  For tree-shaking efficiency and clarity, prefer named imports for individual API operations. The generated file exports functions directly, not a default object.
• api
  wrong:

  const api = require('./my-generated-api');

  correct:

  import * as api from './my-generated-api';

  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.
• generate
  wrong:

  import { generate } from 'oazapfts';

  correct:

  import { generate } from 'oazapfts/generate';

  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.
• RequestOpts
  wrong:

  import { RequestOpts } from 'oazapfts';

  correct:

  import type { RequestOpts } from '@oazapfts/runtime';

  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.

Quickstart

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.

import { mkdir, writeFile } from 'node:fs/promises';
import { generate } from 'oazapfts/generate';

// A minimal OpenAPI spec for demonstration
const openApiSpec = {
  openapi: '3.0.0',
  info: { title: 'Test API', version: '1.0.0' },
  paths: {
    '/items': {
      get: {
        operationId: 'getItems',
        summary: 'Retrieve a list of items',
        responses: { '200': { description: 'A list of items', content: { 'application/json': { schema: { type: 'array', items: { type: 'string' } } } } } }
      },
      post: {
        operationId: 'createItem',
        summary: 'Create a new item',
        requestBody: {
          required: true,
          content: { 'application/json': { schema: { type: 'object', properties: { name: { type: 'string' } } } } }
        },
        responses: { '201': { description: 'Item created' } }
      }
    }
  }
};

async function main() {
  const outputDir = './generated-client';
  await mkdir(outputDir, { recursive: true });
  const outputPath = `${outputDir}/api.ts`;

  // Generate the client code
  const clientCode = await generate({
    spec: openApiSpec,
    url: 'https://example.com/api-docs',
    plugins: [] // You can add custom plugins here
  });

  await writeFile(outputPath, clientCode);
  console.log(`OpenAPI client generated to ${outputPath}`);

  // Example of consuming the generated API (conceptually)
  console.log('\n// To use the generated client (after installing @oazapfts/runtime):');
  console.log(`// import { getItems, createItem } from './generated-client/api';`);
  console.log(`// import { fetch } from '@oazapfts/runtime';`);
  console.log(`// const items = await getItems();`);
  console.log(`// await createItem({ name: 'New Item' });`);
}

main().catch(console.error);