OpenAPI Client Axios

Common errors

• Cannot read properties of undefined (reading 'default')

  cause Attempting to use `require('openapi-client-axios')` directly in CommonJS without accessing the default export of the module.
  fix Modify your import to `const OpenAPIClientAxios = require('openapi-client-axios').default;`.

• Error: definition must be a string (URL) or an object

  cause Passing a local file path (e.g., `./openapi.json`) as the `definition` option, which is no longer supported for file system resolution since v7.0.0.
  fix Provide a URL for the OpenAPI definition, or read the file content yourself and pass the parsed JSON/YAML object directly: `new OpenAPIClientAxios({ definition: yourParsedObject })`.

• ReferenceError: require is not defined in ES module scope

  cause Using CommonJS `require()` syntax in an environment configured for ES Modules (e.g., Node.js with `"type": "module"` in `package.json` or in a browser bundling context expecting ESM).
  fix Replace `require()` with the standard ES Module `import` syntax: `import OpenAPIClientAxios from 'openapi-client-axios';`.

Warnings

• breaking Since v7.0.0, `openapi-client-axios` no longer supports resolving remote `$refs` or loading OpenAPI definitions from local file paths. Definitions must be provided as local URLs or inline JavaScript/JSON objects.
  Fix: Ensure your OpenAPI definition is accessible via a URL (e.g., `https://example.com/api/openapi.json`) or loaded into memory as a JavaScript object before being passed to the `definition` option. Resolve all `$refs` internally or manually if they point to remote locations.
• breaking Version 7.0.0 removed the `@apidevtools/swagger-parser` dependency, replacing it with an internal, simpler dereferencer. This change significantly reduces bundle size but means custom parsing or complex `$ref` resolution strategies previously relying on `swagger-parser` may no longer work.
  Fix: If you relied on specific features or behaviors of `swagger-parser`, you may need to pre-process your OpenAPI definition externally before passing it to `openapi-client-axios`.
• breaking Version 6.0.0 introduced support for `axios` v1 and above. Older versions of `axios` might lead to compatibility issues or unexpected behavior.
  Fix: Upgrade your `axios` dependency to version 1.x or later. Ensure your project's `package.json` reflects a compatible `axios` version (e.g., `"axios": ">=1.0.0"`).
• gotcha When using `openapi-client-axios` in a CommonJS environment (e.g., Node.js without ESM enabled), the `OpenAPIClientAxios` class is exposed as a default export, requiring `.default` to access.
  Fix: Change your import statement from `const OpenAPIClientAxios = require('openapi-client-axios');` to `const OpenAPIClientAxios = require('openapi-client-axios').default;`.

Install

• npm install openapi-client-axios npm
• yarn add openapi-client-axios yarn
• pnpm add openapi-client-axios pnpm

Imports

• OpenAPIClientAxios
  wrong:

  import { OpenAPIClientAxios } from 'openapi-client-axios';

  correct:

  import OpenAPIClientAxios from 'openapi-client-axios';

  The primary class constructor is exported as a default export. For CommonJS environments, use `require('openapi-client-axios').default`.
• Client

  import type { Client } from 'openapi-client-axios';

  Type definition for the dynamically generated API client instance returned by `api.getClient()` or resolved by `api.init()`.
• OpenAPIClient

  import type { OpenAPIClient } from 'openapi-client-axios';

  Type definition for the main OpenAPIClientAxios instance itself, useful when working with the API configuration.

Quickstart

Initializes an OpenAPI client with a public Petstore definition, then demonstrates fetching existing data and creating new resources using the dynamically generated client methods.

import OpenAPIClientAxios from 'openapi-client-axios';
import type { Client } from 'openapi-client-axios';

const PETSTORE_URL = 'https://petstore.swagger.io/v2/swagger.json';

// Initialize the client with the OpenAPI definition URL
const api = new OpenAPIClientAxios({ definition: PETSTORE_URL });

async function fetchAndCreatePet() {
  try {
    // Initialize the API client and get the generated operations
    const client: Client = await api.getClient();

    // Example 1: Fetch all pets (using a method derived from operationId 'findPetsByStatus')
    console.log('Fetching available pets...');
    const availablePetsResponse = await client.findPetsByStatus({ status: ['available'] });
    console.log('Available pets:', availablePetsResponse.data.slice(0, 3)); // Log first 3

    // Example 2: Create a new pet (using operationId 'addPet')
    console.log('\nAdding a new pet...');
    const newPet = {
      id: 987654321,
      name: 'Buddy',
      status: 'available',
      category: { id: 1, name: 'Dogs' },
      photoUrls: ['http://example.com/buddy.jpg']
    };
    const addPetResponse = await client.addPet(newPet);
    console.log('New pet added:', addPetResponse.data);

  } catch (error: any) {
    console.error('An error occurred:', error.message);
    if (error.response) {
      console.error('API Response Data:', error.response.data);
    }
  }
}

fetchAndCreatePet();