在openapi-typescript中注入自定义类型导入的方法

在使用openapi-typescript生成TypeScript类型定义时，开发者经常需要将OpenAPI规范中的某些格式映射到自定义类型。一个常见的需求是将日期时间格式映射到第三方库提供的类型，比如使用Luxon库的DateTime类型替代原生Date类型。

基本转换方法

openapi-typescript提供了transform选项，允许开发者自定义类型转换逻辑。例如，可以将OpenAPI中的date-time格式转换为Luxon的DateTime类型：

const DATE_TIME = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("DateTime"));
const DATE = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("Date")); 
const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull());

const output = await openapiTS(localPath,{
    transform(schemaObject, metadata) {
     if (["date-time", "date"].includes(schemaObject.format)) {
        return schemaObject.nullable
          ? ts.factory.createUnionTypeNode([DATE_TIME, NULL])
          : DATE_TIME;
      }
    },
});

这种方法虽然能正确生成类型引用，但生成的类型定义文件中缺少必要的import语句，导致DateTime类型无法解析。

解决方案：动态注入导入语句

openapi-typescript提供了inject选项，可以在生成的类型定义文件开头注入任意文本。对于简单的场景，可以直接使用这个选项添加import语句：

const output = await openapiTS(localPath, {
    inject: "import { DateTime } from 'luxon';\n\n",
    // ...其他配置
});

然而，这种方法有一个缺点：即使生成的类型中没有使用自定义类型，也会注入不必要的import语句。对于更复杂的场景，可以采用动态注入的方式：

let needsLuxonImport = false;

const typesOutput = await openapiTS(localPath, {
    transform(schemaObject) {
        if (["date-time", "date"].includes(schemaObject.format)) {
            needsLuxonImport = true;
            return ts.factory.createTypeReferenceNode("DateTime");
        }
    },
});

const finalOutput = needsLuxonImport 
    ? `import { DateTime } from 'luxon';\n\n${astToString(typesOutput)}`
    : astToString(typesOutput);

fs.writeFileSync("interfaces.d.ts", finalOutput);

进阶技巧：处理多种自定义类型

在实际项目中，可能需要处理多种自定义类型的映射。可以扩展上述方法，跟踪多种类型的导入需求：

const requiredImports = new Set<string>();

const typesOutput = await openapiTS(localPath, {
    transform(schemaObject) {
        if (schemaObject.format === "date-time") {
            requiredImports.add("DateTime");
            return ts.factory.createTypeReferenceNode("DateTime");
        }
        if (schemaObject.format === "mongo-objectid") {
            requiredImports.add("ObjectId");
            return ts.factory.createTypeReferenceNode("ObjectId");
        }
    },
});

const imports = Array.from(requiredImports)
    .map(type => {
        if (type === "DateTime") return "import { DateTime } from 'luxon';";
        if (type === "ObjectId") return "import { ObjectId } from 'mongodb';";
        return "";
    })
    .join("\n");

const finalOutput = imports 
    ? `${imports}\n\n${astToString(typesOutput)}`
    : astToString(typesOutput);

这种方法既保持了灵活性，又确保了生成的类型定义文件的整洁性，只在真正需要时才添加相应的import语句。

总结

在openapi-typescript中处理自定义类型导入时，开发者应该：

1. 使用transform选项实现类型映射
2. 跟踪实际使用的自定义类型
3. 动态生成必要的import语句
4. 将import语句与生成的类型定义合并输出

这种方法既满足了类型安全的需求，又保持了生成代码的简洁性，是处理自定义类型导入的最佳实践。