# @corpusant/apigen-ts 中文文档

规范地址：https://npmcn.com/package/%40corpusant/apigen-ts/

版本：1\.3\.0
npm 元数据更新时间：2026-02-04T22:25:41.845Z
中文译文更新时间：2026-11-10T22:19:05.314Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40corpusant/apigen-ts
原文对照：https://npmcn.com/package/%40corpusant/apigen-ts/?lang=original
项目主页：https://github.com/vladkens/apigen-ts#readme
源码仓库：https://github.com/vladkens/apigen-ts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：76.5 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：prettier ^3\.0\.0，typescript ^5\.0\.0
- 首次发布：2026-02-04T22:25:41.389Z
- 最新版本发布：2026-02-04T22:25:41.613Z
- 近 30 天下载量：2602（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

简单的 OpenAPI 客户端生成器

## 安装

```sh
npm install @corpusant/apigen-ts
```

也可以使用：`pnpm add @corpusant/apigen-ts`、`yarn add @corpusant/apigen-ts`、`bun add @corpusant/apigen-ts`

## README

# 亚平子

[![version](https://badges.ws/npm/v/apigen-ts)](https://npmjs.org/package/apigen-ts) [![size](https://badges.ws/packagephobia/publish/apigen-ts)](https://packagephobia.now.sh/result?p=apigen-ts) [![downloads](https://badges.ws/npm/dm/apigen-ts)](https://npmjs.org/package/apigen-ts) [![license](https://badges.ws/github/license/vladkens/apigen-ts)](https://github.com/vladkens/apigen-ts/blob/main/LICENSE) [![donate](https://badges.ws/badge/-/buy%20me%20a%20coffee/ff813f?icon=buymeacoffee&label)](https://buymeacoffee.com/vladkens)

![apigen-ts logo](https://npmcn.com/package/%40corpusant/apigen-ts/logo.svg)

## 特征

-   生成准备使用 `ApiClient` 有类型( 使用) `fetch`(中文(简体) )
-   单个输出文件, 最小第三方代码
-   从 JSON / YAML 从本地和远程装入计划
-   定制的能力 `fetch` 带有自定义函数
-   用 Pretier 自动格式化
-   可解析日期- 时间格式( C)`--parse-dates` 旗帜)
-   支持 OpenAPI v2, v3, v3.1
-   也可以与 npx 一起使用

## 安装

```sh
npm install apigen-ts --save-dev
```

```sh
yarn add -D apigen-ts
```

## 使用量

### 1\. 生成

```sh
# From file
npx apigen-ts ./openapi.json ./api-client.ts

# From url
npx apigen-ts https://petstore3.swagger.io/api/v3/openapi.json ./api-client.ts

# From protected url
npx apigen-ts https://secret-api.example.com ./api-client.ts -H "x-api-key: secret-key"
```

运行 `npx apigen-ts --help` 更多选择。 生成客户的例子 [这里](https://npmcn.com/package/%40corpusant/apigen-ts/examples/)。 。 。 .

### 2\. 进口

```ts
import { ApiClient } from "./api-client"

const api = new ApiClient({
  baseUrl: "https://example.com/api",
  headers: { Authorization: "secret-token" },
})
```

### 3\. 使用

```ts
// GET /pet/{petId}
await api.pet.getPetById(1) // -> Pet

// GET /pet/findByStatus?status=sold
await api.pet.findPetsByStatus({ status: "sold" }) // -> Pets[]

// PUT /user/{username}; second arg body with type User
await api.user.updateUser("username", { firstName: "John" })
```

## 高级

### 登录流量

```ts
const { token } = await api.auth.login({ usename, password })
api.Config.headers = { Authorization: token }

await api.protectedRoute.get() // here authenticated
```

### 自动分析日期

```sh
npx apigen-ts ./openapi.json ./api-client.ts --parse-dates
```

```ts
const pet = await api.pet.getPetById(1)
const createdAt: Date = pet.createdAt // date parsed from string with format=date-time
```

### 字符串结合为 enum

您可以生成字符串字面结合, 而不是本地的enums, 以防你想在 Node.js 环境中运行 [类型](https://nodejs.org/api/typescript.html#type-stripping)完成这个传球 `--inline-enums` 命令行参数或使用 `inlineEnums: true` 在节点.js API.

```sh
npx apigen-ts ./openapi.json ./api-client.ts --inline-enums
```

这将生成:

```ts
type MyEnum = "OptionA" | "OptionB"

// instead of
enum MyEnum = {
  OptionA = "OptionA",
  OptionB = "OptionB"
}
```

### 处理错误

所有未成功返回代码都将被排除.

```ts
try {
  const pet = await api.pet.getPetById(404)
} catch (e) {
  console.log(e) // parse error depend of your domain model, e is awaited response.json()
}
```

您也可以定义自定义函数来解析错误 :

```ts
class MyClient extends ApiClient {
  async ParseError(rep: Response) {
    // do what you want
    return { code: "API_ERROR" }
  }
}

try {
  const api = new MyClient()
  const pet = await api.pet.getPetById(404)
} catch (e) {
  console.log(e) // e is { code: "API_ERROR" }
}
```

### 基本url 解析

您可以修改端点url的创建方式 。 默认 [URL 构建器](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) 用于像 : `new URL(path, baseUrl)` 具有特定解析 [规则](https://developer.mozilla.org/en-US/docs/Web/API/URL_API/Resolving_relative_references)例如:

-   `new URL("/v2/cats", "https://example.com/v1/") // -> https://example.com/v2/cats`
-   `new URL("v2/cats", "https://example.com/v1/") // -> https://example.com/v1/v2/cats`

如果您想要自定义端点 URL 解析规则, 您可以覆盖 `PrepareFetchUrl` 方法。 详情见 [问题](https://github.com/vladkens/apigen-ts/issues/2)。 。 。 .

```ts
class MyClient extends ApiClient {
  PrepareFetchUrl(path: string) {
    return new URL(`${this.Config.baseUrl}/${path}`.replace(/\/{2,}/g, "/"))
  }
}

const api = new MyClient({ baseUrl: "https://example.com/v1" })
// will call: https://example.com/v1/pet/ instead of https://example.com/pet/
const pet = await api.pet.getPetById(404)
```

### 节点.js API

创建文件像 `apigen.mjs` 有内容 :

```js
import { apigen } from "apigen-ts"

await apigen({
  source: "https://petstore3.swagger.io/api/v3/openapi.json",
  output: "./api-client.ts",
  // everything below is optional
  name: "MyApiClient", // default "ApiClient"
  parseDates: true, // default false
  inlineEnums: false, // default false, use string literal union instead of enum
  headers: { "x-api-key": "secret-key" }, // Custom HTTP headers to use when fetching schema
  resolveName(ctx, op, proposal) {
    // proposal is [string, string] which represents module.funcName
    if (proposal[0] === "users") return // will use default proposal

    const [a, b] = op.name.split("/").slice(3, 5) // eg. /api/v1/store/items/search
    return [a, `${op.method}_${b}`] // [store, 'get_items'] -> apiClient.store.get_items()
  },
})
```

然后运行 : `node apigen.mjs`

## 使用不同的后端框架

### FastAPI 软件

默认 `apigen-ts` 与 FastAPI 一起使用时生成吵闹方法名称。 这可以由 [自定义解析](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#using-the-path-operation-function-name-as-the-operationid) 行动编号.

```py
from fastapi import FastAPI
from fastapi.routing import APIRoute

app = FastAPI()

# add your routes here

def update_operation_ids(app: FastAPI) -> None:
    for route in app.routes:
        if isinstance(route, APIRoute):
            ns = route.tags[0] if route.tags else "general"
            route.operation_id = f"{ns}_{route.name}".lower()


# this function should be after all routes added
update_operation_ids(app)
```

_注:如果希望FastAPI作为预设添加,请打开PR._

## 比较

-   [openapi-typescript-codegen 代码](https://github.com/ferdikoomen/openapi-typescript-codegen) (单位:千美元)[无](https://www.npmjs.com/package/openapi-typescript-codegen): 无单一文件模式 [1263号](https://github.com/ferdikoomen/openapi-typescript-codegen/issues/1263#issuecomment-1502890838)
-   [openapi 类型标记](https://github.com/drwpow/openapi-typescript) (单位:千美元)[无](https://www.npmjs.com/package/openapi-typescript): 低等 api; 客户端代码中没有要使用的命名类型导出
-   [opalapi- 生成器- cli](https://github.com/OpenAPITools/openapi-generator-cli) (单位:千美元)[无](https://www.npmjs.com/package/@openapitools/openapi-generator-cli):围着java lib打包
-   [斯瓦格类型标记- api](https://github.com/acacode/swagger-typescript-api) (单位:千美元)[无](https://www.npmjs.com/package/swagger-typescript-api): 复杂配置; 用户- api 在版本间断开更改

## 发展

-   [https://ts-ast-viewer.com (中文(中国大陆) )](https://ts-ast-viewer.com/)
-   [https://jsonschemalint.com (中文(中国大陆) )](https://jsonschemalint.com/)
-   [https://redocly.github.io/redoc/ 页面存档备份,存于互联网档案馆](https://redocly.github.io/redoc/)
-   [https://swagger.io/docs/规格/基本结构/](https://swagger.io/docs/specification/basic-structure/)

## 常见问题

### @corpusant/apigen-ts 是什么？

简单的 OpenAPI 客户端生成器

### 如何安装 @corpusant/apigen-ts？

在项目目录运行 npm install @corpusant/apigen-ts，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：prettier（^3\.0\.0）、typescript（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 apigen-ts，可以用 npx apigen-ts 直接运行。

### @corpusant/apigen-ts 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @corpusant/apigen-ts 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @corpusant/apigen-ts 可以商用吗？

@corpusant/apigen-ts 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @corpusant/apigen-ts 的下载量有多少？

根据 npm 官方下载统计，@corpusant/apigen-ts 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,602 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @corpusant/apigen-ts 还在维护吗？

最新版本 1\.3\.0 发布于 2026/02/05（9 个月前）；至今共发布 1 个版本，其中过去 12 个月发布了 1 个；首次发布于 2026/02/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。