AutoAPI

AutoAPI is a tool based on OpenAPI / Swagger documents to automatically generate atomic request methods and TypeScript types.

English | 简体中文

Features

• Atomic Request Methods: Self-contained, reusable anywhere, and tree-shakeable.
• Automatic Type Generation: Eliminates the need to manually maintain parameter and response types, reducing the chance of errors or omissions.
• Type Inference: Converts JSON data into TypeScript types. If documentation is incomplete or unavailable, you can configure manual requests to derive response types.
• Fine-grained Control: Flexible configuration for filtering, grouping, naming conventions, and type structure customization.
• Adapter Mechanism: Custom adapters can be implemented to fit various business scenarios.
• SSR Support: Allows passing context parameters during server-side rendering, with logic for parameter forwarding implemented in adapters.
• Efficient API Structure Management: Supports multiple documents and groupings.

Requirements

• Requires OpenAPI / Swagger documents or manually declared APIs.
• Project must use TypeScript.
• Requires custom implementation of adapter logic—don’t worry, it’s simple.

Installation

npm

npm install -D @autoapi/cli

pnpm

pnpm add -D @autoapi/cli

yarn

yarn add -D @autoapi/cli

Usage

Initialization

npx autoapi --init

After initialization, a .autoapi directory will be created, containing a config.ts configuration file.

Configuration Example

// .autoapi/config.ts

import { defineConfig } from '@autoapi/cli'

export default defineConfig({
  docs: [
    {
      namespace: 'Example',
      adapter: '/path/to/your/adapter.ts',
      source: 'https://api.example.com/autoapi.json' // or YAML
    },

    // More ...
  ]
})

Build Commands

Build All Documents

npx autoapi

Build Specific Documents

npx autoapi -n Foo Bar Baz

Configuration

AutoAPI configuration files are located in the .autoapi directory and can be named as follows:

• config.ts (preferred, executed internally with tsx)
• config.js
• config.cjs
• config.mjs
• config.json

See configuration documentation →

See configuration examples →

Adapter

Here’s how to implement a basic adapter using Axios:

import { RequestOptions } from '@autoapi/cli'
import axios from 'axios'

const instance = axios.create({
  baseURL: 'https://api.example.com'
})

/**
 * Retrieves body data
 * @param options
 */
function getBodyData (options: RequestOptions) {
  const { formData, body } = options

  if (formData) {
    const form = new FormData()
    for (const key in formData) {
      form.append(key, formData[key])
    }
    return form
  }

  return body
}

/**
 * Request Adapter
 * Must export a function named `request`.
 * @param method HTTP method
 * @param path Request path
 * @param options Request options
 */
export function request<T> (method: string, path: string, options: RequestOptions) {
  if (options.context) {
    // Handle parameter forwarding logic for SSR if context parameters are used.
  }

  return instance.request<T>({
    ...options.config,
    method,
    url: path,
    params: options.queryParams,
    data: getBodyData(options),
  })
}

API Structures

File Directory

flowchart LR
    apis["apis"] --> documents@{ shape: docs, label: "[documents]" }
documents --> tags@{ shape: procs, label: "[tags]" }
documents --> schemas@{ shape: braces, label: "schemas.d.ts" }
tags --> index@{ shape: braces, label: "index.ts" }
tags --> types@{ shape: braces, label: "types.d.ts" }

Loading

Operation Methods

flowchart
    Operations@{ shape: procs, label: "[Operations]" }
Operations -.-> request["⬆ Request"]
request --> pathParams
request --> queryParams
request --> headers
request --> formData
request --> body
request --> config
request --> context
Operations -..-> response["⬇ Response"]

style Operations fill: lightpink, stroke: hotpink, color: black
style request fill: lightskyblue, stroke: steelblue, color: black
style response fill: lightgreen, stroke: green, color: black

Loading

Type Declarations

flowchart
    API["declare namespace API"] --> Documents@{ shape: docs, label: "[Documents]" }
Documents --> $parameters --> ParameterTypes@{ shape: procs, label: "[Types]" }
Documents --> $responses --> ResponseTypes@{ shape: procs, label: "[Types]" }
Documents --> $schemas --> SchemaTypes@{ shape: procs, label: "[Types]" }
Documents --> ResponseWrapper
Documents --> Tag@{ shape: procs, label: "[Tags]" } --> Operations@{ shape: procs, label: "[Operations]"}
Operations --> PathParams
Operations --> QueryParams
Operations --> Headers
Operations --> Body
Operations --> Response
Operations --> Responses@{ shape: procs, label: "Responses" }

style Operations fill: lightpink, stroke: hotpink, color: black

Loading

Adapter

mindmap
    Adapter(("Adapter"))
        request["request"]
        RequestConfig["RequestConfig"]
        RequestContext["RequestContext"]

Loading

Acknowledgments

• OpenAPI & Swagger - The OpenAPI Specification, formerly known as the Swagger Specification, is the world’s standard for defining RESTful interfaces. The OAS enables developers to design a technology-agnostic API interface that forms the basis of their API development and consumption.
• change-case - Transform a string between camelCase, PascalCase, Capital Case, snake_case, param-case, CONSTANT_CASE and others.
• openapi-types - Types for OpenAPI documents.
• js-yaml - JavaScript YAML parser and dumper. Very fast.
• node-fetch - A light-weight module that brings the Fetch API to Node.js
• Prettier - An opinionated code formatter.
• APIs.guru - Wikipedia for Web APIs.