OpenAPI SDK Generator

6.1.3 verified Sun Apr 19 auth: no javascript

The `@readme/api` package provides a robust command-line interface and programmatic API for generating SDKs from OpenAPI (formerly Swagger) definitions. It takes an OpenAPI specification file and outputs a fully-typed JavaScript SDK, designed to be consistent across CommonJS, ES Modules, and TypeScript environments. The current stable version is `6.1.3`, with active development towards `v7.0.0`, which introduces significant overhauls to the SDK generation strategy, notably streamlining the process by removing complex configuration questions and enhancing type and module resolution. This package differentiates itself by offering a complete SDK generation pipeline that handles schema imports and type safety, aiming to provide a 'just works' experience for developers integrating with OpenAPI-driven APIs. Its release cadence is active, with minor and patch updates regularly addressing fixes and quality-of-life improvements, while major versions introduce breaking changes and significant architectural shifts.

Common errors

error Error: The '@readme/api' package requires Node.js version X or higher. ↓

cause Attempting to use the package with an incompatible or outdated Node.js version.

fix

Upgrade your Node.js environment to the minimum required version (Node.js 16+ for v6.x, Node.js 20.10.0+ for v7.x).

error SyntaxError: Cannot use import statement outside a module ↓

cause Trying to use ESM `import` syntax in a CommonJS context (e.g., in a `.js` file without `"type": "module"` in `package.json` or older Node.js versions) with `v6.x`.

fix

For v6.x, use const { symbol } = require('@readme/api'); for CommonJS environments. For modern setups or v7.x aiming for ESM consistency, ensure your package.json specifies "type": "module" or use a .mjs file extension.

Warnings

breaking The minimum required Node.js version for `v7.x` has been bumped to `v20.10.0`. ↓

fix Upgrade your Node.js environment to version `20.10.0` or newer, or stick to a `v6.x` release for older Node.js versions.

breaking Version `6.0.0` dropped support for Node.js 14. ↓

fix Ensure your Node.js environment is version 16 or higher when using `v6.x` of the package.

breaking The SDK generation strategy has been overhauled in `v7.x`. This release streamlines the process by removing previous configuration questions and aiming for a 'just works' experience with consistent types and module resolution. ↓

fix Review the `v7.x` changelog and update your programmatic SDK generation calls, as previous configuration options may no longer be supported or necessary.

gotcha A security vulnerability related to the `oas` dependency was resolved in `v6.1.3`. ↓

fix Upgrade to `@readme/api@6.1.3` or newer to ensure you have the latest security patches.

Install

npm install api

yarn add api

pnpm add api

Imports

generate
wrong
```
const { generate } = require('@readme/api');
```
correct
```
import { generate } from '@readme/api';
```
Since v7, the package offers consistent module resolution for both ESM and CJS. For v6, CommonJS `require` was standard.
APIOptions
```
import type { APIOptions } from '@readme/api';
```
Type import for configuration options when programmatically generating an SDK. The actual export name is 'options'.
*
wrong
```
const api = require('@readme/api');
```
correct
```
import * as api from '@readme/api';
```
Imports all named exports into a namespace object. Useful for accessing multiple utilities or when specific named imports are not desired.

Quickstart

Demonstrates how to programmatically generate a TypeScript-ready SDK from a dummy OpenAPI specification using the `generate` function, then cleans up the temporary files. This is runnable in a modern Node.js environment supporting ESM.

import { generate } from '@readme/api';
import path from 'node:path';
import fs from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

async function createDummyOpenApiSpec(specPath: string) {
  const dummyOpenApiSpec = {
    openapi: '3.0.0',
    info: { title: 'My API', version: '1.0.0' },
    paths: {
      '/users': {
        get: {
          summary: 'Get all users',
          responses: {
            '200': {
              description: 'A list of users',
              content: { 'application/json': { schema: { type: 'array', items: { $ref: '#/components/schemas/User' } } } }
            }
          }
        }
      }
    },
    components: {
      schemas: {
        User: {
          type: 'object',
          properties: {
            id: { type: 'string', format: 'uuid' },
            name: { type: 'string' }
          }
        }
      }
    }
  };
  await fs.writeFile(specPath, JSON.stringify(dummyOpenApiSpec, null, 2));
}

async function runSdkGeneration() {
  const outputBaseDir = path.resolve(__dirname, 'temp-sdk-output');
  await fs.mkdir(outputBaseDir, { recursive: true });

  const openApiPath = path.join(outputBaseDir, 'openapi.json');
  await createDummyOpenApiSpec(openApiPath);

  const sdkOutputDir = path.join(outputBaseDir, 'generated-sdk');
  await fs.mkdir(sdkOutputDir, { recursive: true });

  console.log(`Starting SDK generation...`);
  console.log(`  OpenAPI Spec: ${openApiPath}`);
  console.log(`  Output Dir: ${sdkOutputDir}`);

  // The '@readme/api' package provides a `generate` function to create SDKs
  // from an OpenAPI definition. It expects the path to the OpenAPI
  // file and the desired output directory for the generated SDK.
  // In v7, the generation strategy is overhauled for consistent module
  // resolution and types across CJS, ESM, and TypeScript.
  await generate(openApiPath, sdkOutputDir);

  console.log('SDK generation complete!');
  console.log(`You can now find the generated SDK in: ${sdkOutputDir}`);
  console.log(`Example: const { default: sdk } = await import('${sdkOutputDir}');`);

  // Clean up temporary files
  await fs.rm(outputBaseDir, { recursive: true, force: true });
  console.log(`Cleaned up temporary directory: ${outputBaseDir}`);
}

runSdkGeneration().catch(console.error);