openapi-axios

library0.34.0jsnpmunverified

A code generator that converts OpenAPI 2.0/3.0/3.1 specifications into type-safe Axios functions with full TypeScript support. Current stable version is 0.34.0, released on a continuous cadence. Key differentiators include optional request/response validation via Zod, support for generating intermediate schema files, and built-in API mocking capabilities. It uses the OpenAPI spec to generate strongly typed request functions that integrate seamlessly with Axios, enabling tree-shaking and type safety.

devops

npm install openapi-axios

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENAPI-AXIOS

openapi-axios

devopsjavascriptv0.34.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig

✓ import { defineConfig } from 'openapi-axios'

✗ import { defineConfig } from 'openapi-axios/client'

defineConfig is a named export from the main package, not a subpath. Available since v0.1.0.

OpenAPIAxios

✓ import { OpenAPIAxios } from 'openapi-axios'

✗ import { OpenAPIAxios } from 'openapi-axios/lib'

OpenAPIAxios is the class for programmatic usage, exported from the main entry point. Do not import from lib/* paths.

GenerateOptions

✓ import type { GenerateOptions } from 'openapi-axios'

✗ import { GenerateOptions } from 'openapi-axios'

GenerateOptions is a TypeScript type; use type import to avoid runtime bundling.

Initializes a config file, generates type-safe Axios functions from an OpenAPI spec, then uses the generated addPet function with full type checking.

// openapi.config.cjs const { defineConfig } = require('openapi-axios'); module.exports = defineConfig({ documents: { petStore: 'https://petstore3.swagger.io/api/v3/openapi.json' } }); // Run: npx openapi-axios // Generated: src/apis/petStore.ts, src/apis/petStore.type.ts // src/app.ts import axios from 'axios'; import { addPet } from './apis/petStore'; import type { AddPetData } from './apis/petStore.type'; const newPet: AddPetData = { name: 'Fluffy', photoUrls: ['https://example.com/fluffy.jpg'] }; addPet(newPet).then(response => { console.log('Pet created:', response.data); }).catch(err => { console.error('Failed to add pet:', err); });

Debug

Known issues

gotchaThe generated code uses axios imported from 'axios' (default import). If you have a different Axios instance, you may need to configure the generated files manually or use the programmatic API.

fix

Use the programmatic API with a custom Axios instance: new OpenAPIAxios({ axiosInstance: customAxios }).

affects: >=0.1.0

deprecatedThe 'init' command is deprecated in favor of manual config creation. Running 'npx openapi-axios init' may be removed in a future major version.

fix

Manually create openapi.config.cjs or openapi.config.js using defineConfig().

affects: >=0.30.0

gotchaThe generated functions return axios response types, but the actual data shape is typed via generics. If you skip TypeScript, you lose type safety.

fix

Always use TypeScript to get the full benefit of the library.

affects: >=0.1.0

gotchaWhen using Zod validation, the generated request functions will throw a ZodError on validation failure. This may not be caught if you only handle Axios errors.

fix

Wrap calls in try-catch that handles both AxiosError and ZodError, or disable validation.

affects: >=0.20.0

Errors

Common errors & fixes

Cannot find module 'openapi-axios' or its corresponding type declarations.

The package is installed as a dev dependency but not built or imported correctly.

fix

Ensure openapi-axios is in devDependencies and run `npm install`. For TypeScript, add `moduleResolution: 'node'` in tsconfig.json.

TypeError: defineConfig is not a function

Using require() on the ES module version of the package.

fix

Use a .cjs extension or use ES module syntax. The package exports both ESM and CJS via module/require fields.

The 'init' command requires a file named 'openapi.config.cjs' to be present.

Running 'npx openapi-axios init' while not having a config file already.

fix

Just run 'npx openapi-axios init' without a pre-existing config; it creates one, but if you see this error, you might have a misconfigured setup. Try deleting any partial config and re-running.

Cannot generate files because axios is not installed.

axios is a required peer dependency but not listed as a regular dependency.

fix

Install axios as a regular dependency: npm install axios

Upgrade

Version history

0.34.0latest on npm

Audit

Dependencies

axiosrequiredRuntime peer dependency for making HTTP requests

zodoptionalOptional dependency for request/response validation

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/FrontEndDev-org/openapi-axios ↗

packageopenapi-axios ↗

homepagehttps://github.com/FrontEndDev-org/openapi-axios ↗