# @haddowg/json-api-codegen 中文文档

规范地址：https://npmcn.com/package/%40haddowg/json-api-codegen/

版本：2\.19\.0
npm 元数据更新时间：2026-11-16T23:01:45.915Z
中文译文更新时间：2026-11-17T05:51:09.171Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40haddowg/json-api-codegen
原文对照：https://npmcn.com/package/%40haddowg/json-api-codegen/?lang=original
项目主页：https://haddowg.github.io/json-api-ts/
源码仓库：https://github.com/haddowg/json-api-ts

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

- 包体积（解压后）：573 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-07-13T10:50:35.778Z
- 最新版本发布：2026-11-16T23:01:45.566Z
- 近 30 天下载量：8518（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

读取 json-api- symfony OpenAPI spec(+ JSON Schemas) 的 CLI ,并释出一个打入的客户端描述符 .

## 安装

```sh
npm install @haddowg/json-api-codegen
```

也可以使用：`pnpm add @haddowg/json-api-codegen`、`yarn add @haddowg/json-api-codegen`、`bun add @haddowg/json-api-codegen`

## README

# @ haddowg/ json- api- 代码源

> **部分 [jsonapi.rest (英语)](https://jsonapi.rest/) 套间** - 完整、符合规格 JSON: API 1. 1 堆栈: 框架不可知 PHP [核心项目](https://github.com/haddowg/json-api)页:1 [符号捆绑](https://github.com/haddowg/json-api-symfony)页:1 [Laravel 软件包](https://github.com/haddowg/json-api-laravel)这个 **键入类型脚本 客户端**,由经过检测的OpenAPI 3.1合同捆绑在一起. 完整文档: **[(原始内容存档于2018-10-21) (韩语). haddog.github.io/json-api-ts](https://haddowg.github.io/json-api-ts/)**。 。 。 .

阅读以下内容的CLI(和方案性API) [`haddowg/json-api-symfony`](https://github.com/haddowg/json-api-symfony) OpenAPI 3.1 文档和 输出一个输入的客户端:运行时间描述符,每类属性界面,以及描述符绑定 `createClient`。可选地读取捆绑的 JSON Schemas 以发布每类图示 [客户端](https://npmcn.com/package/%40haddowg/client) 选入验证接合.

OpenAPI 文档已针对运行时间的需要完全自定义——类型身份 (单位:千美元)`properties.type.const`),关系核心和相关类型,允许 `?include` 路径( 每个端点的边框、 预先扩展的enum), 创建客户端id 政策和 paginator 类型。 代码仅读取 spec; 所有真正的工作都是通用运行时机械 in `@haddowg/json-api-client`。 。 。 .

## 安装

A. 对非宗教的依赖—— **生成的产出** 没有返回代码的运行时带( 它导入) `@haddowg/json-api-client`) (中文(简体) ).

```bash
pnpm add -D @haddowg/json-api-codegen
```

安装了两个 bin 名称 : `json-api-codegen` 和简称 `japi`。 。 。 .

编码源读取了发电机合同文件24至40(`info.x-generator.contract`) (中文(简体) ). 新来的 文档仍然生成,同时警告客户端可能错过服务器添加的内容,以及 旧代码被拒绝 : 它以这个代码不再读取的形式描述其错误代码 . 任何服务器标记贬值得到的 `@deprecated` TSDoc,所以编辑通过它.

## 国 际

```bash
json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--examples] [--check]
```

| 旗帜 | 需求 | 说明 |
| --- | --- | --- |
| `--input` | 对 | OpenAPI 文档源 — 一个 http( s) URL 或本地文件路径( JSON 或 YAML) . |
| `--output` | 对 | 用于生成客户端的输出文件(例如. `src/api/music.gen.ts`) (中文(简体) ). |
| `--server` | 没有 | 要瞄准的服务器名 。 仅元数据——已送达的文档已经是每个服务器. |
| `--schemas` | 没有 | JSON Schema源(URL或路径)用于验证接合. 跳过计划输出. |
| `--examples` | 没有 | 还要给兄弟们写行动的例子 `.examples.gen.ts` 模块. |
| `--check` | 没有 | 漂流门——在内存中再生,如果承诺输出不同,则退出非零. |

示例 – 以已送达的API 生成,并附有验证方案:

```bash
json-api-codegen \
  --input https://music.example/docs.json \
  --output src/api/music.gen.ts \
  --schemas https://music.example/schemas.json
```

这写道:

-   `src/api/music.gen.ts` ——打入的客户端(描述器+类型+绑定) `createClient`(三);
-   `src/api/music.schemas.gen.ts` ——每型 JSON Schema 映射(仅使用 `--schemas`) (中文(简体) ).
-   `src/api/music.examples.gen.ts` ——每个行动都有行之有效的例子(只有 `--examples`,以及 仅当文件宣布一些时).

计划文物路径来源于 `--output`(单位:千美元) `.gen.ts` 后缀变为 `.schemas.gen.ts`, (中文(简体) ), 一个平面 `.ts` 变成 `.schemas.ts`。 。 。 .

> **提交生成的文件 .** 喜欢 `openapi-typescript` 编号 : `graphql-codegen`,输出为一 在您的 repo 中小,可审查,可分发,版本化模块——不是已发布的软件包. 重新生成 当 API 更改时.

### 证明章

每件生成的文物都在其头部有出处记录——出处谱标识符 (单位:千美元)`<info.title> <info.version>`),第一个宣布的服务器 URL,以及稳定的 16-hex 内容散列 源文件(图案文物带有 `Schema hash` 以图图谋。 没错 **时间戳和确定性**:从相同的 spec 产量字节-等同输出中再生出. 散列告诉一个评论员 承诺的客户端是哪个来源的 然后让漂流门 下面比较重生成的输出字节换字节.

```
/**
 * AUTO-GENERATED by @haddowg/json-api-codegen — do not edit by hand.
 * Regenerate from the source OpenAPI document instead.
 *
 * Source spec: Music Catalog API 1.0.0
 * Server:      https://music.example
 * Spec hash:   40e273dff0411f68
 */
```

### 漂流检查( R)`--check`(中文(简体) )

`--check` 在记忆中再生,并与承诺进行比较 `--output` (及其计划) 兄长何时 `--schemas` 设置) **没有写任何东西**。它会打印出每幅画 `ok`编号 :`DRIFT` 如果缺少任何已执行文件或已过时,则行并退出非零。 把它接入CI——接上 因此一个 stale 生成的客户端失败了构建:

```bash
json-api-codegen \
  --input spec/music-catalog.openapi.json \
  --output src/api/music.gen.ts \
  --schemas spec/music-catalog.schemas.json \
  --check
```

### 多个服务器

捆绑每个服务器服务一个OpenAPI文档(例如. `default` 财务报告和审定财务报表 `admin` 它们的差别 类型集和路径前缀)。 通过指向每个服务器生成一个客户端 `--input` 在每个服务器上 文档 – 每个服务器有一个输入的客户端 .

## 它会产生什么

输出模块导出 :

-   `resourceMap` ——运行时间描述符(`as const`) 什么情况 [查询](https://npmcn.com/package/%40haddowg/query) 软件包 正常化需要.
-   `ResourceMap` —— 说 `typeof resourceMap`。 。 。 .
-   `createClient(options)` ——有描述符的工厂(描述符和服务器的 `atomic` 能力被烤入; 您只提供 [`ClientOptions`](https://npmcn.com/package/%40haddowg/client)) (中文(简体) ).
-   `Attributes` 编号 : `WriteAttributes` ——每类属性图(读 vs 创建/更新).
-   按类型 `…Attributes` 编号 : `…CreateAttributes` 编号 : `…UpdateAttributes` 接口、 enum 类型 (例如:. `AlbumStatus`),被命名为形状(例如. `Reviewer`),以及动作输入/输出类型.
-   `Links` ——每类中输入的已声明链接 .
-   `ErrorCodes` 编号 : `ErrorCode` 编号 : `ErrorCodeByStatus` 编号 : `ErrorCodeByOperation` 编号 : `ErrorMetaByCode` 编号 : `hasErrorCode` 编号 : `findError` ——服务器的已记录错误代码,只有一些代码 操作提升,每个代码的键入 `meta`以及一个看守和发现者.
-   `pageLimits` 编号 : `relatedPageLimits` – 每集的页面默认和页面大小上限以及 每个相关的收藏.
-   `pageKinds` 编号 : `relatedPageKinds` ——标注策略 每一集及相关 收藏报价, 服务器先默认 .

与 `--schemas`,兄弟模块导出 `schemas` ——每型JSON Schema 2020-12地图.

```ts
import { createClient, type ResourceMap, resourceMap } from './api/music.gen'
import { schemas } from './api/music.schemas.gen'

const client = createClient({ baseUrl: 'https://music.example' })
```

### 动词/ 关系相撞

如果一个类型在资源控件上有一个像保留动词一样命名的关系(`get`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `rel`, (中文(简体) ), `actions`,...),代码表达a **构建时间警告** 和该关系路线 结束 `.rel('name')` 在流利的客户端中;普通案件保持不变.

## 程序化 API

同一代人,可以从剧本调用(`japi.config.ts`,一个建设步骤等):

```ts
import { generate, type CodegenConfig } from '@haddowg/json-api-codegen'

const config: CodegenConfig = {
  input: 'https://music.example/docs.json',
  output: 'src/api/music.gen.ts',
  schemas: 'https://music.example/schemas.json', // optional
  server: 'default', // optional, metadata-only
}

await generate(config) // writes the output file(s); returns the client source string
```

漂流门也是有计划的—— `check(config)` 内存和返回中的再生 `{ ok, artifacts }` (每件货物) `{ path, upToDate }`)不写:

```ts
import { check } from '@haddowg/json-api-codegen'

const result = await check({ ...config, check: true })
if (!result.ok) process.exit(1)
```

低层构件也出口用于高级用途: `readDocument` 编号 : `readSchemas`, (中文(简体) ), `buildDescriptor`, (中文(简体) ), `buildExamples`, (中文(简体) ), `emit`, (中文(简体) ), `emitSchemas`, (中文(简体) ), `emitExamples`, (中文(简体) ), `readErrorCatalogue`, (中文(简体) ), `emitErrorCodes`, (中文(简体) ), `checkContract`, (中文(简体) ), `detectVerbCollisions`, (中文(简体) ), `schemasOutputPath`, (中文(简体) ), `examplesOutputPath`和从何而来的援助者 `deriveProvenance` 编号 : `provenanceLines` 编号 : `hashJson`。 。 。 . `generateFiles(config)` 生成像 `generate` 并返回它所写的路径.

## 许可证

麻省理工学院

## 常见问题

### @haddowg/json-api-codegen 是什么？

读取 json-api- symfony OpenAPI spec\(\+ JSON Schemas\) 的 CLI ,并释出一个打入的客户端描述符 \.

### 如何安装 @haddowg/json-api-codegen？

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

### @haddowg/json-api-codegen 支持 TypeScript 吗？

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

### @haddowg/json-api-codegen 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @haddowg/json-api-codegen 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @haddowg/json-api-codegen 可以商用吗？

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

### @haddowg/json-api-codegen 的下载量有多少？

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

### @haddowg/json-api-codegen 还在维护吗？

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

