# openapi-tool

> a tool to generate service file based on openapi

Latest version **0.5.1** (published 2026-03-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install openapi-tool
pnpm add openapi-tool
yarn add openapi-tool
bun add openapi-tool
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.1 |
| Published | 2026-03-13 |
| First published | 2021-07-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 101.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 41 |
| Author | Joey Hua |
| Maintainers | joeyhua |
| Keywords | node, swagger, openapi |

## Links

- npm: https://www.npmjs.com/package/openapi-tool
- Repository: https://github.com/huajiayi/openapi-tool
- Homepage: https://github.com/huajiayi/openapi-tool#readme
- Issues: https://github.com/huajiayi/openapi-tool/issues
- npm.io page: https://npm.io/package/openapi-tool

## Dependencies (3)

- [ejs](https://npm.io/package/ejs.md) ^3.1.6
- [umi-request](https://npm.io/package/umi-request.md) ^1.3.9
- [openapi-tool](https://npm.io/package/openapi-tool.md) file:

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 0.5.1 (latest) — 2026-03-13
- 0.5.0 — 2026-02-28
- 0.4.12 — 2025-08-15
- 0.4.11 — 2024-09-29
- 0.4.10 — 2023-07-28
- 0.4.9 — 2023-07-28
- 0.4.8 — 2023-07-28
- 0.4.7 — 2023-07-06
- 0.4.6 — 2023-04-23
- 0.4.5 — 2023-04-08
- 0.4.4 — 2023-04-08
- 0.4.3 — 2023-01-29
- 0.4.2 — 2023-01-29
- 0.4.1 — 2022-12-29
- 0.3.6 — 2022-04-09
- … 18 more at https://npm.io/package/openapi-tool/versions

## README

# openapi-tool

English | [简体中文](https://github.com/huajiayi/openapi-tool/blob/main/README_CN.md)

openapi-tool is a tool to generate service file based on openapi.

If you like it, please give me a star. Thanks a lot!

### Features

- Compatible with bath [OAS2](https://swagger.io/specification/v2/) and [OAS3](https://swagger.io/specification/)
- Support major HTTP Client([axios](https://github.com/axios/axios) and [umi-request](https://github.com/umijs/umi-request) so far)
- Support generating js or ts file
- Support type system when generate ts file
- Plugin system to add global-level functionality

### Install

```
npm install openapi-tool
```

### Example

#### note: CommonJS usage

In order to gain the TypeScript typings (for intellisense / autocomplete) while using CommonJS imports with `require()` use the following approach:

```js
const OpenApiTool = require('openapi-tool').default;
```

**PS: Typing `.default` is merely used to gain the TypeScript typings. Please remove `.default` when you launch the project, otherwise it will throw an error.**

#### Usage

```js
const OpenApiTool = require('openapi-tool');
const { resolve } = require('path');

const url = 'https://gw.alipayobjects.com/os/antfincdn/M%24jrzTTYJN/oneapi.json';
const outputDir = resolve(__dirname, 'service');

const openApiTool = new OpenApiTool({url});
openApiTool.generateService({
  template: 'axios',
  importText: `const axios = require('axios');`,
  typescript: true,
  outputDir,
});
```

### API

#### `new OpenApiTool(options: Options)`

Create a new `OpenApiTool` instance.

**Options:**

| Property | Description | Type | Default | required |
| ------ | ------ | ------ | ------ | ------ |
| url | The url of swagger document  | string | - | either url or data |
| data | The json of swagger document | string | - | either url or data |

#### `generateService(options: ServiceGeneratorOptions): void`

Generate service files, the name of file will be the tag's name.

**ServiceGeneratorOptions:**

| Property | Description | Type | Default | required |
| ------ | ------ | ------ | ------ | ------ |
| outputDir | Output directory  | string | - | true |
| template | HTTP client template which you want to generate  | string | `'umi-request'` | false |
| importText | Import statements  | string | `default statements` | false |
| typescript | Generate ts file and typings  | boolean | `false` | false |
| format | Format content of OpenApi  | (openapi: OpenApi) => OpenApi | - | false |
| genericFields | generic fields  | string[] | - | false |

#### `getOpenApi(): Promise<OpenApi>`

Get OpenApi that transformed from OAS2/OAS3.

### Plugin

openapi-tool have a flexible plugin system which can add global-level functionality. 

#### Using Plugin

Use plugins by calling the `OpenApiTool.use()` global method. This has to be done before you start your app by calling `new OpenApiTool()`:

```js
// calls `MyPlugin.install(OpenApiTool)`
OpenApiTool.use(MyPlugin)

new OpenApiTool({
  //... options
})
```

You can optionally pass in some options:

```js
OpenApiTool.use(MyPlugin, { someOption: true })
```

#### Writing a plugin

A plugin should be a method. The method will be called with the `OpenApiTool` constructor as the first argument, along with possible options:

```js
const logPlugin = (OpenApiTool, option) => {
  OpenApiTool.prototype.log = async function() {
    const openapi = await this.getOpenApi();
    console.log(`the length of apis: ${openapi.apis.length}`);
    console.log('option', option);
  }
}
```

then you can use it like this:

```js
const openApiTool = new OpenApiTool({
  //... options
});
openApiTool.log();
```

### License

[MIT](https://github.com/huajiayi/openapi-tool/blob/main/LICENSE)

---
_Source: https://npm.io/package/openapi-tool · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._