Configuration

genapi defines API generation behavior through configuration files. Configuration files support TypeScript, JavaScript, or JSON formats.

Configuration File

Create one of the following configuration files in your project root:

genapi.config.ts
genapi.config.js
genapi.config.json

Basic Configuration

import { defineConfig } from '@genapi/core'
import { axios } from '@genapi/presets'

export default defineConfig({
  preset: axios.ts,
  input: 'https://petstore3.swagger.io/api/v3/openapi.json',
  output: {
    main: 'src/api/index.ts',
    type: 'src/api/index.type.ts',
  },
})

Preset configuration that defines how APIs are generated. You can use either a pipeline object (from @genapi/presets) or a preset string (resolved at runtime, e.g. @genapi/presets/swag-axios-ts).

Pipeline object (recommended):

import { axios, tanstackQuery } from '@genapi/presets'

preset: axios.ts   // or axios.js
preset: tanstackQuery.react
preset: tanstackQuery.vue
preset: tanstackQuery.colada

Preset string (default is 'swag-axios-ts'):

HTTP: swag-axios-ts, swag-axios-js, swag-fetch-ts, swag-fetch-js, swag-ky-ts, swag-ky-js, swag-got-ts, swag-got-js, swag-ofetch-ts, swag-ofetch-js, swag-uni-ts, swag-uni-js
Data layer: tanstack-react, tanstack-vue, colada

HTTP clients (.ts / .js): axios, fetch, ky, got, ofetch, uni

Data layer (TypeScript only): tanstackQuery.react, tanstackQuery.vue, tanstackQuery.colada

input

Input source, which can be:

URL string: Directly pass in the API documentation URL
```
input: 'http://example.com/api-docs'
```

Object: uri, json, or http (ofetch options)

input: { uri: 'http://example.com/api-docs' }
input: { json: { /* OpenAPI JSON */ } }
input: { json: './openapi.json' }
input: { http: { /* ofetch FetchOptions */ } }

parser

Parser type for input source. Determines how the input data is parsed:

'swagger' (default): Supports OpenAPI 2.0/3.x and Swagger 2.0 formats
'wpapi': Supports WordPress REST API format, automatically converts to Swagger

Example with WordPress REST API:

export default defineConfig({
  preset: axios.ts,
  parser: 'wpapi', // or 'swagger'
  input: 'https://your-wordpress-site.com/wp-json',
  output: {
    main: 'src/api/index.ts',
  },
})

output

Output configuration: generated file paths.

output: {
  main: 'src/api/index.ts',       // Main entry (or hooks file for query presets)
  type: 'src/api/index.type.ts', // Type definitions (optional; set to false to omit)
  api: 'src/api/index.api.ts',   // Optional; used by TanStack/Colada presets for fetcher APIs
}

For query presets (TanStack Query, Colada), the default is three files: main (hooks), api (fetchers), type (types). You can override output.main, output.api, and output.type.

Multiple Services

For projects with multiple services, use the servers configuration:

export default defineConfig({
  // All servers inherit the upper layer configuration
  meta: {
    baseURL: 'https://example.com/api',
  },
  servers: [
    {
      input: 'http://service1/api-docs',
      output: { main: 'src/api/service1.ts' }
    },
    {
      input: 'http://service2/api-docs',
      output: { main: 'src/api/service2.ts' }
    },
  ]
})

Patch - Static Patches

Make exact-match modifications to operations and type definitions:

export default defineConfig({
  preset: axios.ts,
  input: 'https://petstore.swagger.io/v2/swagger.json',
  patch: {
    operations: {
      // Rename function
      postUpdateUserUsingPOST: 'updateUserInfo',
      // Modify parameters and return type
      getUserUsingGET: {
        name: 'getUser',
        parameters: [{ name: 'id', type: 'string', required: true }],
        responseType: 'UserResponse'
      }
    },
    definitions: {
      // Rename type
      UserDto: 'User',
      // Override type (creates type alias)
      SessionDto: {
        name: 'Session',
        type: '{ name: string, age: number }'
      }
    }
  }
})

Transform - Global Transformations

Batch transform operations and definitions via functions. Transform runs first; patch is applied after.

Signatures:

operation(name, parameters, responseType) → new name string or { name?, parameters?, responseType? }
definition(name, type) → new name string or { name?, type? } (type is the array of field definitions)

export default defineConfig({
  preset: axios.ts,
  input: 'https://petstore.swagger.io/v2/swagger.json',
  transform: {
    operation: (name) => `api_${name}`,
    definition: (name, type) => name.endsWith('Dto') ? name.slice(0, -3) : name,
  },
  patch: {
    operations: { api_getUser: 'fetchUser' },
  },
})

MockJS - Mock Data Generation

Generate mock methods for each API function (requires better-mock). Enable via meta.mockjs:

export default defineConfig({
  preset: axios.ts,
  input: 'https://petstore.swagger.io/v2/swagger.json',
  meta: { mockjs: true },
})

Usage:

import { getUser } from './api'

const mockUser = getUser.mock() // Returns mock data conforming to type definitions

Getting Started

Presets