深入理解openapi-typescript的Node.js API使用

最新推荐文章于 2025-06-06 09:05:11 发布

原创最新推荐文章于 2025-06-06 09:05:11 发布 · 368 阅读

CC 4.0 BY-SA版权

深入理解openapi-typescript的Node.js API使用

openapi-typescript Generate TypeScript types from OpenAPI 3 specs 项目地址: https://gitcode.com/gh_mirrors/ope/openapi-typescript

前言

在现代Web开发中，OpenAPI规范已成为描述RESTful API的标准方式。而openapi-typescript项目则提供了一种将OpenAPI规范转换为TypeScript类型定义的强大工具。本文将重点介绍其Node.js API的使用方法，帮助开发者更灵活地集成到项目中。

安装与基础配置

首先需要安装openapi-typescript作为开发依赖：

npm install --save-dev openapi-typescript

为了获得最佳体验，建议在项目的package.json中添加ES模块支持：

{
  "type": "module"
}

核心API使用方法

openapi-typescript的Node API提供了多种加载OpenAPI规范的方式：

1. 从内存中的JSON对象加载

import fs from "node:fs";
import openapiTS from "openapi-typescript";

const schema = await fs.promises.readFile("spec.json", "utf8");
const output = await openapiTS(JSON.parse(schema));

2. 从本地文件加载（支持YAML和JSON）

const localPath = new URL("./spec.yaml", import.meta.url);
const output = await openapiTS(localPath);

3. 从远程URL加载（支持YAML和JSON）

const output = await openapiTS("https://myurl.com/v1/openapi.yaml");

需要注意的是，直接传入YAML字符串不被支持，需要先转换为JSON格式。

高级配置选项

除了支持所有CLI标志的camelCase版本外，Node API还提供了额外的配置选项：

| 选项名称 | 类型 | 默认值 | 描述 | |----------------|----------------|-------|----------------------------------------------------------------------| | commentHeader | string | | 覆盖默认的文件头注释 | | inject | string | | 在文件开头注入自定义TypeScript类型 | | transform | Function | | 在特定场景下覆盖默认的Schema对象到TypeScript的转换逻辑 | | postTransform | Function | | 与transform类似，但在TypeScript转换后执行 | | cwd | string | URL | | 提供当前工作目录以解析远程$ref引用（仅内存中的JSON对象需要） |

自定义类型转换

transform和postTransform选项提供了强大的自定义能力，让我们看几个实际案例：

日期时间类型转换

默认情况下，date-time格式会被转换为string类型。我们可以通过transform自定义为Date类型：

const types = openapiTS(mySchema, {
  transform(schemaObject, metadata) {
    if ("format" in schemaObject && schemaObject.format === "date-time") {
      return schemaObject.nullable ? "Date | null" : "Date";
    }
  },
});

转换结果：

-  updated_at?: string;
+  updated_at?: Date;

文件上传类型处理

对于文件上传场景中的binary格式字段，可以转换为Blob类型：

const types = openapiTS(mySchema, {
  transform(schemaObject, metadata) {
    if ("format" in schemaObject && schemaObject.format === "binary") {
      return schemaObject.nullable ? "Blob | null" : "Blob";
    }
  },
});

转换结果：