openapi-ts-request

When you use a configuration file that contains an array of multiple service configurations, the CLI defaults to an interactive mode (if --interactive is enabled).

Instead of running all tasks at once, the CLI will present a multiselect prompt (using @clack/prompts) allowing you to choose which specific services from the configuration array you want to generate. If you cancel the selection, the process terminates gracefully.

# If your config file looks like this:
[
  { "schemaPath": "api1.yaml", "serversPath": "./api1" },
  { "schemaPath": "api2.yaml", "serversPath": "./api2" }
]

# Running the command will prompt:
# "请选择要生成的 service" (Please select the service to generate)

You can use npx or pnpm to run the CLI directly without adding it to your project dependencies to preview the output. Use the -i flag for the input schema and -o for the output directory.

# Using npm/npx
npx --package=openapi-ts-request -- openapi -i ./openapi.json -o ./apis --isGenReactQuery=true
npx --package=openapi-ts-request -- openapi -i https://petstore3.swagger.io/api/v3/openapi.json -o ./apis --isGenReactQuery=true

# Using pnpm
pnpm --package=openapi-ts-request@latest dlx openapi -i ./openapi.json -o ./apis --isGenReactQuery=true
pnpm --package=openapi-ts-request@latest dlx openapi -i https://petstore3.swagger.io/api/v3/openapi.json -o ./apis --isGenReactQuery=true

Use npx to run the generator without a permanent configuration file by passing arguments directly.

# Using npm
npx --package=openapi-ts-request -- openapi -i ./openapi.json -o ./apis
npx --package=openapi-ts-request -- openapi -i https://petstore3.swagger.io/api/v3/openapi.json -o ./apis

# Using pnpm
pnpm --package=openapi-ts-request@latest dlx openapi -i ./openapi.json -o ./apis
pnpm --package=openapi-ts-request@latest dlx openapi -i https://petstore3.swagger.io/api/v3/openapi.json -o ./apis

The openapi CLI tool generates TypeScript or JavaScript services from an OpenAPI specification. You can run it in two ways:

1. Directly via arguments: Provide --input (path or URL) and --output (directory) to trigger immediate generation.
2. Via configuration files: Provide --configFilePath or --configFileName to load settings from a file. If multiple configurations are found in the file, the CLI enters an interactive mode to let you select which services to generate.

If no input/output arguments are provided and no configuration file is found, the CLI will exit with an error.

# Example: Generate using direct arguments
openapi --input ./swagger.yaml --output ./src/api

# Example: Generate using a specific config file
openapi --configFilePath ./configs/api-config.json

To generate a request client from an existing Swagger or OpenAPI schema, create an openapi-ts-request.config.ts file in your project root. Define your configuration using the GenerateServiceProps type, specifying the schemaPath. You can then run the generation via a script in your package.json.

import type { GenerateServiceProps } from 'openapi-ts-request';

export default [
  {
    schemaPath: 'https://petstore3.swagger.io/api/v3/openapi.json',
  },
] as GenerateServiceProps[];

Add this to your package.json:

"scripts": {
  "openapi": "openapi-ts"
}

Run the command:

npm run openapi

You can programmatically trigger code generation by creating a configuration file and running it with Node.js or ts-node.

// For TypeScript (run with ts-node)
// openapi-ts-request.config.ts
const { generateService } = require('openapi-ts-request');

generateService({
  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
  serversPath: './apis',
});

// For JavaScript (run with node)
// openapi-ts-request.config.js
const { generateService } = require('openapi-ts-request');

generateService({
  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
  serversPath: './apis',
});

You can install openapi-ts-request as a development dependency using npm or pnpm to generate TypeScript/JavaScript client request functions, types, and mock services from OpenAPI/Swagger specifications.

# npm
npm i openapi-ts-request --save-dev

# pnpm
pnpm i openapi-ts-request -D

Enable isGenReactQuery: true to generate React Query compatible options and hooks. For GET requests, it generates queryOptions functions. For POST, DELETE, and PATCH requests, it generates custom mutation hooks.

import type { GenerateServiceProps } from 'openapi-ts-request';

export default [
  {
    schemaPath: 'https://petstore3.swagger.io/api/v3/openapi.json',
    requestLibPath: '@/core/request/index.ts',
    isGenReactQuery: true,
  },
] as GenerateServiceProps[];

If your API paths in the schema do not include the gateway prefix required for actual requests (e.g., /user, /manage), use the apiPrefix option to prepend a string to all generated paths.

export default [
  {
    schemaPath: 'http://127.0.0.1:4523/export/openapi/2?version=3.0',
    requestLibPath: '@/core/request/index.ts',
    apiPrefix: '"/user"',
  },
  {
    schemaPath: 'http://127.0.0.1:4523/export/openapi/3?version=3.0',
    requestLibPath: '@/core/request/index.ts',
    apiPrefix: '"/manage"',
  },
] as GenerateServiceProps[];

If you only need the TypeScript type definitions and do not want the generated request functions, set isOnlyGenTypeScriptType: true in your configuration.

import type { GenerateServiceProps } from 'openapi-ts-request';

export default [
  {
    schemaPath: 'http://127.0.0.1:4523/export/openapi/2?version=3.0',
    requestLibPath: '@/core/request/index.ts',
    isOnlyGenTypeScriptType: true,
  },
] as GenerateServiceProps[];