@ 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 并返回它所写的路径.
许可证
麻省理工学院