@ archastro/ sdk- 生成器

生成已键入的 TypeScript, Python, Swift, Go, Elixir, 和 Rust SDKs —— 加上跨语言 合同测试——取自ArchAstro API DSL生产的OpenAPI光谱.

安装

# ad-hoc
npx @archastro/sdk-generator --spec ./openapi.json --lang typescript --out ./sdk

# global
npm install -g @archastro/sdk-generator
sdk-generator --spec ./openapi.json --lang python --out ./sdk

国 际

sdk-generator --spec <openapi.json> \
                  [--lang typescript|python|swift|go|elixir|rust|contract-tests-ts|contract-tests-py|contract-tests-swift|contract-tests-go|contract-tests-elixir|contract-tests-rust] \
                  [--out <dir>] \
                  [--config <config.json>] \
                  [--ast-only]

目标:

去目标配置

去解析类型 财务报告和审定财务报表 从一个软件包级命名空间的函数,及其 每个目录编译一个软件包,所以 Go后端需要软件包名称 和导入路径呼叫者到达它。 两者都生活在配置文件下面 go数字 :

{
  "go": {
    "packageName": "platform",
    "importPath": "github.com/ArchAstro/archastro-go/platform"
  }
}

SDK平地着陆 <out>/<packageName>/ (单位:千美元)types_*.go, (中文(简体) ), v1_*.go, (中文(简体) ), channels_*.go, (中文(简体) ), client.go, (中文(简体) ), auth.go合同测试 <out>/contracttests/,通过这条路径导入 SDK 。 发射器 写入结构正确 Go, 而不是列对齐 Go —— 运行 gofmt -w 结束 输出作为再生的一部分.

生成的 SDK 文档

生成器将 OpenAPI 文档保存为平面源文件 语言。 使用标准 OpenAPI 字段作为真理的来源 :

• 运行 summary 财务报告和审定财务报表 description 成为 TypeScript JSDoc, Python 方法剂量弦,和斯威夫特/去 // 文件评论.
• 参数和请求体字段 description 值成为参数 和输入对象字段文件.
• 成功响应描述成为了返回值文件.
• 司马 description 值变为 TypeScript 接口/schema docs 并 Python模型多克弦.
• Schema 属性 description 值变为 TypeScript 字段 Docs, Zod .describe(...) 元数据,和 Pydantic Field(description=...) 元数据.

对于消耗 SDK repos , 将 Docs 生成保留在生成的软件包旁边 :

• 类型脚本:添加类型Doc, 点 entryPoints 在公众生成的条目 点,并公布生成的 docs/ 有 GitHub 页面的目录.
• Python: 添加 pdoc, 将其指向生成的软件包, 并发布渲染的 带有 GitHub Pages 的 HTML .
• 在 SDK 重生失败后运行 CI 中的文件构建 在释放前.

--config

两个后端所消耗的共享编码元数据 :

{
  "name": "@archastro/platform-sdk",
  "version": "0.1.0",
  "baseUrl": "https://platform.archastro.ai",
  "apiBase": "/api",
  "defaultVersion": "v1",
  "description": "ArchAstro Platform API SDK"
}

TypeScript 客户端扩展

已生成 PlatformClient 类 显示类型 类表达式混合接合 :

const RealtimePlatformClient = PlatformClient.extend(
  withCustomObjectSubscriptions,
);
const client = RealtimePlatformClient.withToken("pk_live_...", accessToken);

extend 返回子类而不是修改 PlatformClient扩展 因此,保留所生成的资源,可以连锁,并由 制造出静态工厂。 手持扩展使用标准 TypeScript 混入形状 :

const withDiagnostics = <TBase extends PlatformClientConstructor>(Base: TBase) =>
  class extends Base {
    diagnosticLabel() {
      return "ready";
    }
  };

消费SDK可以使这些模块在整个再生过程中保持公开,而无需 向发电机传授方法:

{
  "typescript": {
    "clientExtensionModules": ["./custom-object-subscriptions.js"]
  }
}

每个已配置的模块作为 export * 生成的条目 包装桶。 模块本身仍然手持.

程序使用

import {
  parseOpenApiSpec,
  generateTypeScript,
  generatePython,
  generateContractTests,
} from "@archastro/sdk-generator";

const spec = JSON.parse(readFileSync("openapi.json", "utf-8"));
const ast = parseOpenApiSpec(spec, { name: "@archastro/platform-sdk" });
const files = generateTypeScript(ast, { outDir: "./sdk" });

发展

这个包裹住在 archastro-openapi 工作空间。 见根 README 构建 / 测试 / 发布指令 .