# @api-ts/openapi-generator 中文文档

规范地址：https://npmcn.com/package/%40api-ts/openapi-generator/

版本：6\.1\.11
npm 元数据更新时间：2026-08-18T14:34:20.637Z
中文译文更新时间：2026-11-06T09:51:17.543Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：288 kB，79 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2022-04-18T21:18:10.380Z
- 最新版本发布：2026-08-18T14:34:20.274Z
- 近 30 天下载量：42766（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：151（近 12 个月 23 个）

## 中文简介

从 io- ts- http 合同生成 OpenAPI 规格

## 安装

```sh
npm install @api-ts/openapi-generator
```

也可以使用：`pnpm add @api-ts/openapi-generator`、`yarn add @api-ts/openapi-generator`、`bun add @api-ts/openapi-generator`

## README

# @ api- ts/ openapi- 生成器

亚庇Ts **openapi 生成器** 是一个用于转换 io- ts- http 的命令行工具 API 规格为 OpenAPI 规格.

## 目录

1.  [安装](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-1-install)
2.  [使用量](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-2-use)
3.  [为可再使用的编码器准备类型包](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-3-preparing-a-types-package-for-reusable-codecs)
4.  [定义自定义编码器的计划](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-4-defining-custom-codecs)
5.  [支持的io- ts原始人列表](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-5-list-of-supported-io-ts-primitives)
6.  [发电机参考](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-6-generator-reference)
    1.  [端点文档](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-61-endpoint-documentation)
    2.  [Schema 文档](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-62-schema-documentation)

## 1\. 安装

```shell
npm install --save-dev @api-ts/openapi-generator
```

## 2\. 用途

这个 **openapi 生成器** 假设io-ts-http `apiSpec` 在顶层导出 作为输入参数通过的 Typescript 文件。 OpenAPI 规格将 写给stdout.

```shell
ARGUMENTS:
  <file> - API route definition file

OPTIONS:
  --name, -n <str>       - API name [optional]
  --version, -v <str>    - API version [optional]
  --codec-file, -c <str> - Custom codec definition file [optional]

FLAGS:
  --internal, -i - include routes marked private
  --help, -h     - show help
```

例如:

```shell
npx openapi-generator src/index.ts
```

## 3\. 为可再使用的编码器准备一个类型包

为了使用外部类型 `io-ts` 类型软件包,您必须确保两样东西 结束了.

1.  包源代码必须包含在捆绑中, 因为生成器是建到 生成基于 Typescript AST 的光谱。 它不是用来与 转接的js代码。 你可以通过修改你的 `package.json` 包含您的 捆绑中的源代码 。 例如,如果源代码存在于 `src/` 目录,然后添加 `src/` 中的文件数组 `package.json` 你的项目.
2.  步骤一之后,更改 `source` 区域 `package.json` 作为切入点 的类别。 例如,如果进入点是 `src/index.ts`, (中文(简体) ), 然后设定 `"source": "src/index.ts"` 输入 `package.json`

## 4\. 定义自定义编码

合作时 `openapi-generator`,您可能会遇到处理自定义的挑战 需要 JavaScript 解释或本地支持的代码 发电机 这些问题通常与编码器如: `new t.Type(...)` 其他项目 不直接支持的原始人. 不过,有两个解决办法需要解决: 这些挑战是有效的。 点击 [这里](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-5-list-of-supported-io-ts-primitives) 页:1 支持原始人列表.

### 解决方案1:在类型包中定义自定义代码Schemas(建议)

`openapi-generator` 现在提供了定义自定义编码器的策略的能力 直接在定义它们的类型包内,而不是下游包内 用他们。 这种方法对于许多文书中使用的解码器特别有用 不同类型包。 以下是您如何定义您的自定义编码器的策略 上游仓库 :

1.  创建名为的文件 `openapi-gen.config.js` 在您的仓库的根部.
    
2.  添加以下一行到 `package.json` 类型包:
    
    ```json
    "customCodecFile": "openapi-gen.config.js"
    ```
    
    您还必须添加 `"openapi-gen.config.js"` 到软件包中的文件字段, 以便包含在最后的捆绑中.
    
3.  在那个 `openapi-gen.config.js` 文件,定义自定义解码器 :
    
    ```javascript
    module.exports = (E) => {
      return {
        SampleCodecDefinition: () =>
          E.right({
            type: 'string',
            default: 'defaultString',
            minLength: 1,
          }),
        // ... rest of your custom codec definitions
      };
    };
    ```
    

通过这些步骤,您的自定义解码器的策略将包含在 生成了 API 文档,用于使用相应编码器的任何端点。 输入参数 `E` 是名称空间导入 `fp-ts/Either`,返回类型应为: `Record` 包含外部库的 AST 定义。 详情见 [已知的进口](https://npmcn.com/package/%40api-ts/openapi-generator/src/knownImports.ts)。 。 。 .

### 解决方案2: 使用自定义代码配置文件

`openapi-generator` 支持从其他软件包导入编码器 `node_modules`不过 它与挣扎 `io-ts` 需要 JavaScript 解释的原始人, 如 `new t.Type(...)`。要围绕这个问题开展工作,您可以在一个 下游类型包中的配置文件(其中生成 API) (中文(简体) ). 这使得生成器能够理解和在必要时使用这些计划. 遵循这些步骤创建和使用自定义代码配置文件 :

1.  创建 JavaScript 文件,格式如下 :
    
    ```javascript
    module.exports = (E) => {
      return {
        'io-ts-bigint': {
          BigIntFromString: () => E.right({ type: 'string' }),
          NonZeroBigInt: () => E.right({ type: 'number' }),
          NonZeroBigIntFromString: () => E.right({ type: 'string' }),
          NegativeBigIntFromString: () => E.right({ type: 'string' }),
          NonNegativeBigIntFromString: () => E.right({ type: 'string' }),
          PositiveBigIntFromString: () => E.right({ type: 'string' }),
        },
        // ... and so on for other packages
      };
    };
    ```
    
2.  输入参数 `E` 是名称空间导入 `fp-ts/Either`,从而避免 问题 `require`。返回类型应为: `Record` 包含 AST 的 外部图书馆的定义。 有关该结构的更多信息,请参阅: [已知的进口](https://npmcn.com/package/%40api-ts/openapi-generator/src/knownImports.ts)。 。 。 .
    

## 5\. 被支持的io-ts原始人名单

-   `string`
-   `number`
-   `bigint`
-   `boolean`
-   `null`
-   `nullType`
-   `undefined`
-   `unknown`
-   `any`
-   `array`
-   `readonlyArray`
-   `object`
-   `type`
-   `partial`
-   `exact`
-   `strict`
-   `record`
-   `union`
-   `intersection`
-   `literal`
-   `keyof`
-   `brand`
-   `UnknownRecord`
-   `void`

## 6\. 发电机参考

本节将突出此生成器支持的所有特性, 并举例 帮助您在您的代码中添加有意义的文档,允许客户端使用我们 APIs与轻松.

### 6.1. 端点文件

鉴于使用定义的终点 `h.httpRoute`,可以添加文档和元数据到 通过使用JS Docs,这个终点. 以下是以下属性列表: 被支持.

#### 6.1.1 总结

摘要为"JSDoc"第一行. 这将添加到 OpenAPI 作为终点摘要的规格

```typescript
/**
 * This is the summary
 */
const route = h.httpRoute({ ... })
```

#### 6.1.2 说明

说明是下一个 `x` jSDoc的未标记行. 这将添加到 OpenAPI 规格作为终点描述

```typescript
/**
 * This is the summary
 * This is description line 1
 * This is description line 2
 */
const route = h.httpRoute({ ... })
```

#### 6.1.3 行动身份证

所有终点必须有一个 `operationId` 被识别。 您可以添加操作ID 改为使用 `@operationId` 在JSDocs的标签。 这会增加它 此路由的 OpenAPI 规格 .

```typescript
/**
 * This is the summary
 * This is description line 1
 * This is description line 2
 *
 * @operationId v2.sample.route
 */
const route = h.httpRoute({ ... })
```

#### 6.1.4 标记

标记是我们如何将终点组织成不同的组 `dev-portal`。有许多 不同的标记和标记组,例如 `Wallet`, (中文(简体) ), `Address`等 (中文(简体) ). [点击这里](https://github.com/BitGo/dev-portal/blob/master/app/lib/apiDocs/apiNavGroups.ts) 为完整的标签列表。 您可以使用 `@tag` JSDoc标签.

```typescript
/**
 * This is the summary
 * This is description line 1
 * This is description line 2
 *
 * @operationId v2.sample.route
 * @tag Wallet
 */
const route = h.httpRoute({ ... })
```

#### 6.1.5 私人路线

在很多情况下,你会希望一个终点是私人的,例如: `admin` 或者说 `internal` 路线。 在文档中,您只需添加一个 `@private` 标记为 JSDoc 。 在规格中,将增加 `x-internal: true` 字段,表示在预处理中要剥去的字段 [步骤](https://github.com/BitGo/dev-portal/blob/master/scripts/filterSpec.js) 打开 dev-portal. (原始内容存档于2018-09-27).

```typescript
/**
 * This is the summary
 * This is description line 1
 * This is description line 2
 *
 * @private
 * @operationId v2.sample.route
 * @tag Wallet
 */
const route = h.httpRoute({ ... })
```

#### 6.1.5.1 公共路线

明确标明一条路线为公共路线(制作) `x-internal: false`),使用 `@public` 标签。 当您的 CI 管道强制所有端点明确声明时, 这样做是有用的 他们的能见度.

```typescript
/**
 * This is the summary
 * This is description line 1
 * This is description line 2
 *
 * @public
 * @operationId v2.sample.route
 * @tag Wallet
 */
const route = h.httpRoute({ ... })
```

> **说明:** 使用两者 `@public` 财务报告和审定财务报表 `@private` 在同一路径或字段上将产生 错误.

#### 6.1.6 不稳定路线

如果你正在研究一个不稳定或尚未完全执行的终点, 您可以添加 `@unstable` 标签以确保消费者知道它仍在开发中 并且可能无法如预期的那样工作.

```typescript
/**
 * This is the summary
 * This is description line 1
 * This is description line 2
 *
 * @unstable
 * @operationId v2.sample.route
 * @tag Wallet
 */
const route = h.httpRoute({ ... })
```

#### 6.1.7 实例

您也可以在您的端点的顶级JS Docs中添加实例响应, 但作为 你会看到以后的章节, 还有其他方法做到这一点.

```typescript
/**
 * This is the summary
 * This is description line 1
 * This is description line 2
 *
 * @unstable
 * @operationId v2.sample.route
 * @tag Wallet
 * @example { example: { object: { key: value }}}
 */
const route = h.httpRoute({ ... })
```

#### 6.1.8 未知标记

在此顶级添加的任何其他标记都将归类为无名标记,以及 将放在 `x-unknown-tags` openAPI 规格中的字段。 你们可以 使用此功能为您全部写入自定义工作流程和过滤逻辑 规格。 例如,您可以添加一个 `@version` 标签和工作流程 过滤基于版本字段的端点 `x-unknown-tags` 字段.

```typescript
/**
 * This is the summary
 * This is description line 1
 * This is description line 2
 *
 * @unstable
 * @operationId v2.sample.route
 * @tag Wallet
 * @example { example: { object: { key: value }}}
 * @version 3
 */
const route = h.httpRoute({ ... })
```

#### 6.1.9 抽样产出

这就是OpenAPI的规格 对我们建造的路线来说是什么样的.

```javascript
{
  "openapi": 3.03,
  "paths": {
    "/api/v2/sample/route": {
      "get": {
        "summary": "This is the summary",
        "description": "This is description line 1\nThis is description line 2",
        "operationId": "v2.sample.route",
        "example": {
          "object": {
            "key": "value"
          }
        },
        "tag": "Wallet",
        "x-internal": true, // @private
        "x-unstable": true, // @unstable
        "x-unknown-tags": {
          "version": 3
        }
        ...parameters,
        ...requestBody,
        ...responses
      }
    }
  }
}
```

### 6.2. Schema 文档

除了为顶级线路添加JSDocs之外,您还可以为以下线路添加JSDocs: 平分仪、请求体和反应体计划.

#### 6.2.1 说明

只要在上方添加一个JSDoc,并加上一个 说明.

```typescript
import * as t from 'io-ts';

/**
 * This is a description that will be included in the OpenAPI specification.
 */
const schema = t.type({
  field: t.number,
});
```

#### 6.2.2 支持的 OpenAPI 标记

这些是您可以在 JS Doc 中设置的 OpenAPI 标签列表,并将包含其中 在生成的 OpenAPI spec 中.

-   `@default[value: any]`
-   `@example [example: any]`
-   `@minLength [length: number]`
-   `@maxLength [length: number]`
-   `@pattern [pattern: regex]`
-   `@minimum [min: number]`
-   `@maximum [max: number]`
-   `@minItems [minItems: number]`
-   `@maxItems [maxItems: number]`
-   `@minProperties [min: number]`
-   `@maxProperties [max: number]`
-   `@exclusiveMinimum`
-   `@exclusiveMaximum`
-   `@multipleOf [num: number]`
-   `@uniqueItems`
-   `@readOnly`
-   `@writeOnly`
-   `@format [format: format]`
-   `@title [title: string]`

以下是所有这些标记在使用的示例计划。 不要担心田地,只是 注意每个领域的不同联合来文和联合来文标记。 您还可以添加多少 标记为您想要的一个字段(条件是标记不冲突)。 您还可以添加 [说明](https://npmcn.com/package/%40api-ts/openapi-generator/#readme-621-descriptions)

```typescript
include * as t from 'io-ts';

/** @title Sample Schema Title */
const SampleSchema = t.type({
  /** @default defaultValueForField1 */
  field1: t.string,
  /** @example exampleForField2 */
  field2: t.string,
  /** @minLength 4 */
  field3: t.string,
  /** @maxLength 6 */
  field4: t.string,
  /** @pattern ^[0-9a-f]{32}$ */
  fieldWithId: t.string,
  /** @minimum 10 */
  minField: t.number,
  /** @maximum 40 */
  maxField: t.number,
  /** @minItems 10 */
  minItemsArray: t.array(t.string),
  /** @maxItems 50 */
  maxItemsArray: t.array(t.string),
  /** @minProperties 3 */,
  minPropRecord: t.record(t.string, t.string),
  /** @maxProperties 10 */
  maxPropRecord: t.record(t.string, t.string),
  nestedObject: t.partial({
    /**
     * @minimum 2
     * @exclusiveMinimum
     */
    exclMin: t.number,
    /**
     * @maximum 50
     * @exclusiveMaximum
     */
    exclMax: t.number,
    /** @multipleOf 5*/
    multOf: t.number,
    /** @uniqueItems */
    arr: t.array(t.string),
    /** @readOnly */
    readOnlyField: t.unknown,
    /** @writeOnly */
    writeOnlyField: t.unknown,
    /** @format uuid */
    uuidField: t.string,
    /** @title Hello */
    titleField: t.string
  })
})
```

#### 6.2.3 自定义标记

这些都是一些标签,你可以使用 在你的计划JSDocs是定制 这个生成器.

-   `@private` 允许您将任何计划中的字段标为私有。 最终会 有过 `x-internal: true` 与计划 `@private` 标签.
-   `@public` 允许您明确标记任何计划中的任何字段为公开字段。 最终 spec 会有 `x-internal: false` 与计划 `@public` 标签。 使用两者 `@public` 财务报告和审定财务报表 `@private` 在同一字段上会出现错误.
-   `@deprecated` 允许将任何计划中的字段标记为已贬值。 最后的轮廓 将包括 `deprecated: true` 在最后的特莱克顿.

```typescript
import * as t from 'io-ts';

const Schema = t.type({
  /** @private */
  privateField: t.string,
  /** @public */
  publicField: t.string,
  /** @deprecated */
  deprecatedField: t.string,
  untaggedField: t.string,
});
```

#### 6.2.3.1 联盟请求机构

当请求机构被定义为 `t.union` 联 合 国 `httpRequest` 计划(接受其中之一) 多个相互排斥的形状),描述必须放在 **联合编码c 本身**,而不是单个变体:

```typescript
import * as t from 'io-ts';
import * as h from '@api-ts/io-ts-http';

/**
 * The member to add — supply either a userId or an email address.
 */
const AddMemberRequest = t.union([
  h.httpRequest({ body: { userId: t.string } }),
  h.httpRequest({ body: { email: t.string } }),
]);

const route = h.httpRoute({
  path: '/enterprise/{enterpriseId}/members',
  method: 'POST',
  request: AddMemberRequest,
  response: { 200: t.string },
});
```

这能产生 `description` 打开 `requestBody.content['application/json'].schema`,哪个 满足 `missing-request-body-description` 质量检查.

> **说明:** 把联合来文文件放在个人身上 `httpRequest(...)` 页:1 工会包装 **没有** 向人体图案传播描述 说明必须在工会编码器上.

#### 6.2.4 Enum文档

使用时 `t.keyof` 以定义 enums,您可以添加描述和折旧通知 到单个素值。 这些将输出为 `x-enumDescriptions` 财务报告和审定财务报表 `x-enumsDeprecated` 在 OpenAPI 规格中.

-   **`@description`** - 添加一个特定激发值的描述。 所有符号值 说明被收集到 `x-enumDescriptions` openAPI 规格中的对象.
-   **`@deprecated`** - 标出已贬值的具体enum值。 所有已贬值的语句 将数值收集到 `x-enumsDeprecated` openAPI 光谱中的数组.

```typescript
import * as t from 'io-ts';

/**
 * Transaction status values
 */
export const TransactionStatus = t.keyof(
  {
    /**
     * @description Transaction is waiting for approval from authorized users
     */
    pendingApproval: 1,
    /**
     * @description Transaction was canceled by the user
     * @deprecated
     */
    canceled: 1,
    /**
     * @description Transaction was rejected by approvers
     * @deprecated
     */
    rejected: 1,
    /**
     * @description Transaction has been successfully completed
     */
    completed: 1,
  },
  'TransactionStatus',
);
```

这将生成以下 OpenAPI 计划 :

```json
{
  "TransactionStatus": {
    "type": "string",
    "enum": ["pendingApproval", "canceled", "rejected", "completed"],
    "x-enumDescriptions": {
      "pendingApproval": "Transaction is waiting for approval from authorized users",
      "canceled": "Transaction was canceled by the user",
      "rejected": "Transaction was rejected by approvers",
      "completed": "Transaction has been successfully completed"
    },
    "x-enumsDeprecated": ["canceled", "rejected"]
  }
}
```

## 常见问题

### @api-ts/openapi-generator 是什么？

从 io- ts- http 合同生成 OpenAPI 规格

### 如何安装 @api-ts/openapi-generator？

在项目目录运行 npm install @api-ts/openapi-generator，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 openapi-generator，可以用 npx openapi-generator 直接运行。

### @api-ts/openapi-generator 支持 TypeScript 吗？

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

### @api-ts/openapi-generator 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @api-ts/openapi-generator 可以商用吗？

@api-ts/openapi-generator 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @api-ts/openapi-generator 的下载量有多少？

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

### @api-ts/openapi-generator 还在维护吗？

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