AutoAPI is a tool designed to generate TypeScript types and request methods based on OpenAPI/Swagger documents. Below is a detailed description of its core configuration options.
English | 简体中文
Defines a list of document configurations to process.
Yes
Defines shared configuration for multiple documents, reducing duplicate definitions.
Omit<DocumentOptions, 'namespace' | 'source'>
Specifies the output directory for generated request methods and types.
string
src/apis
Determines whether to store downloaded documents on disk for version control or backup purposes.
boolean
false
Detailed configuration options for individual documents.
Specifies the namespace for the document, used to categorize generated request methods and types.
string
Yes
Specifies the path to the request adapter, either as a local file path or a module alias.
string
Yes (can be defined in shared configuration)
const options = {
adapter: 'path/to/adapter/file.ts',
};
const options2 = {
adapter: '@/utils/request.ts',
};Defines the source of the document, which can be a remote URL, a local file path, a document object, or an asynchronous function returning the document.
string | object | (() => string | object | Promise<string | object>)
-
Remote Document
const options = { source: 'https://api.example.com/autoapi.json', // Supports JSON or YAML };
-
Local Document
const options = { source: path.resolve(__dirname, './docs/autoapi.json'), // Supports JSON or YAML };
-
Document Object
const options = { source: { /* OpenAPI.Document */ }, };
-
Custom Asynchronous Fetch
const options = { source: async () => { const res = await fetch('https://api.example.com/autoapi.json'); return res.json(); }, };
Defines the interfaces or paths to include, supporting filtering by tags, paths, or custom logic.
Filters
-
Filter by Tags
const options = { include: ['Tag1', 'Tag2'], };
-
Filter by Paths
const options = { include: { '/path/to/api': true, '/path/to/api2': ['get', 'post'], }, };
-
Custom Logic
const options = { include: (meta: OperationMeta) => meta.path.includes('/user'), };
Defines the interfaces or paths to exclude, using the same filtering rules as include.
Filters
Top-level namespace for generated API types, used to organize interfaces and types hierarchically.
string
API
Specifies the parameter type for request configuration, such as AxiosRequestConfig.
Defines the type of context parameters for requests, especially useful for server-side rendering (SSR).
Specifies the type wrapper for response data, used to handle discrepancies between actual response structures and those defined in the document.
const options = {
responseWrapper: {
type: 'object',
properties: [
{ name: 'data', type: 'T' },
],
},
};Specifies the path to access response data, adjusting the return type of the operation method.
string
const options = {
responseReturnPath: '.data',
};Customizes the logic for generating interface paths.
(meta: OperationMeta) => string
Customizes the logic for grouping interfaces.
(meta: OperationMeta) => string
Customizes the logic for generating method names.
(meta: OperationMeta) => string
Defines the naming style for method names.
camel | pascal | snake
camel
Controls whether to optimize generated method names, such as adding [method] prefixes and removing redundant parts.
boolean
true
Custom logic for determining whether an HTTP status code indicates a successful request.
(code: number) => boolean
200~299
Determines whether to parse responses for unsuccessful requests, based on validateStatus.
boolean
Allows complete customization of operation information and structure or declaration of undocumented interfaces.
{ [path: string]: OperationHandlers }
const options = {
paths: {
'/path/to/api': {
get: {
name: 'customMethodName',
tag: 'CustomTag',
types: {
// pathParams: {}
queryParams: {
type: 'object',
properties: [
{
name: 'page',
type: 'number',
},
{
name: 'size',
type: 'number',
}
]
},
// headers: {}
// formData: {}
// body: {}
response: async () => {
return {
type: 'inference',
input: await fetch('http://api.example.com/get-some-list').then((res) => res.json()),
}
}
}
},
// post: {}
// put: {}
// delete: {}
}
}
}export type Filters = FilterPaths | (FilterPaths | string)[] | ((meta: OperationMeta) => boolean)
export interface FilterPaths {
[Path: string]: boolean | HttpMethods[]
}export interface ParameterOptions {
required?: boolean
disabled?: boolean
}/**
* Type definition
*/
export type TypeDefinition =
| undefined // unknown
| null // unknown
| string // Literal: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
| ObjectType
| ArrayType
| EnumType
| IntersectionType
| UnionType
| GenericType
| InferenceType
| ReferenceType
/**
* Object Type
* @docs https://www.typescriptlang.org/docs/handbook/2/objects.html
*/
export interface ObjectType {
type: 'object'
properties: PropertySignature[]
}
/**
* Property Signature Type
*/
export interface PropertySignature {
name: string
type: TypeDefinition
description?: string
required?: boolean
deprecated?: boolean
additional?: boolean // additionalProperties, `[P: string]: any`
schema?: SchemaObject & {
default?: any
format?: string
}
}
/**
* Array Type
* @docs https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#arrays
*/
export interface ArrayType {
type: 'array'
items: TypeDefinition[]
}
/**
* Enum Type
*/
export interface EnumType {
type: 'enum'
items: (string | number)[]
}
/**
* Intersection Type (AND)
* @docs https://www.typescriptlang.org/docs/handbook/2/objects.html#intersection-types
*/
export interface IntersectionType {
type: 'intersection'
items: TypeDefinition[]
}
/**
* Union Type (OR)
* @docs https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types
*/
export interface UnionType {
type: 'union'
items: TypeDefinition[]
}
/**
* Generic Type (Foo<a, b, c>)
* @docs https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-types
*/
export interface GenericType {
type: 'generic'
name: string
arguments: TypeDefinition[]
}
/**
* Inference Type (Inference of type from the input)
* @docs https://www.typescriptlang.org/docs/handbook/type-inference.html#handbook-content
*/
export interface InferenceType {
type: 'inference'
input: any
required?: boolean
}
/**
* Reference Type (OpenAPI)
*/
export interface ReferenceType<T = any> {
type: 'reference'
value: string
target: T
body: TypeDefinition
}