@haddowg/json-api-codegen

中文文档
2.19.0发布于 2026/11/17MITTypeScriptES Module构建来源已验证近 30 天下载 8518

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

中文使用文档
文档目录9 节
  1. 安装
  2. 国 际
  3. 证明章
  4. 漂流检查( R) --check (中文(简体) )
  5. 多个服务器
  6. 它会产生什么
  7. 动词/ 关系相撞
  8. 程序化 API
  9. 许可证

@ haddowg/ json- api- 代码源

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

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

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

安装

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

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

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

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

国 际

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 生成,并附有验证方案:

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 生成的客户端失败了构建:

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) 什么情况 查询 软件包 正常化需要.
  • ResourceMap —— 说 typeof resourceMap。 。 。 .
  • createClient(options) ——有描述符的工厂(描述符和服务器的 atomic 能力被烤入; 您只提供 ClientOptions) (中文(简体) ).
  • 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地图.

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,一个建设步骤等):

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 })不写:

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 共发布 49 个版本,首次发布于 2026/07/13;过去 12 个月发布了 49 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.19.0latest2026/11/17今天
2.18.12026/11/17今天
2.18.02026/11/16今天
2.17.02026/11/133 天前
2.16.12026/11/133 天前
2.16.02026/11/133 天前

关于 @haddowg/json-api-codegen 的常见问题

@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 和提交记录判断。