feat: Add the inject option (#1766)

* feat: Add the inject option

* Create little-pets-perform.md

Author: phk422

.changeset/little-pets-perform.md

@@ -0,0 +1,6 @@
+---
+"openapi-typescript-docs": minor
+"openapi-typescript": minor
+---
+
+feat: Add the inject option

docs/node.md

@@ -89,6 +89,7 @@ The Node API supports all the [CLI flags](/cli#options) in `camelCase` format, p
 | `postTransform` |   `Function`    |                 | Same as `transform` but runs _after_ the TypeScript transformation                           |
 | `silent`        |    `boolean`    |     `false`     | Silence warning messages (fatal errors will still show)                                      |
 | `cwd`           | `string \| URL` | `process.cwd()` | (optional) Provide the current working directory to help resolve remote `$ref`s (if needed). |
+| `inject`        |    `string`     |                 | Inject arbitrary TypeScript types into the start of the file                                 |
 
 ### transform / postTransform
 

docs/zh/node.md

@@ -89,6 +89,7 @@ Node API 支持所有 [CLI 参数](/zh/cli#命令行参数)（采用 `camelCase`
 | `postTransform` |   `Function`    |                 | 与 `transform` 相同，但在 TypeScript 转换之后运行               |
 | `silent`        |    `boolean`    |     `false`     | 静默警告消息（致命错误仍将显示）                                |
 | `cwd`           | `string \| URL` | `process.cwd()` | （可选）提供当前工作目录以帮助解析远程 `$ref`（如果需要的话）。 |
+| `inject`        |    `string`     |                 | 在文件开头注入任意的 TypeScript 类型   |
 
 ### transform / postTransform
 

packages/openapi-typescript/src/index.ts

@@ -83,6 +83,7 @@ export default async function openapiTS(
     propertiesRequiredByDefault: options.propertiesRequiredByDefault ?? false,
     redoc,
     silent: options.silent ?? false,
+    inject: options.inject ?? undefined,
     transform: typeof options.transform === "function" ? options.transform : undefined,
     resolve($ref) {
       return resolveRef(schema, $ref, { silent: options.silent ?? false });

packages/openapi-typescript/src/transform/index.ts

@@ -1,5 +1,5 @@
 import ts, { type InterfaceDeclaration, type TypeLiteralNode } from "typescript";
-import { NEVER, STRING, tsModifiers, tsRecord } from "../lib/ts.js";
+import { NEVER, STRING, stringToAST, tsModifiers, tsRecord } from "../lib/ts.js";
 import { createRef, debug } from "../lib/utils.js";
 import type { GlobalContext, OpenAPI3 } from "../types.js";
 import transformComponentsObject from "./components-object.js";
@@ -19,6 +19,11 @@ const transformers: Record<SchemaTransforms, (node: any, options: GlobalContext)
 export default function transformSchema(schema: OpenAPI3, ctx: GlobalContext) {
   const type: ts.Node[] = [];
 
+  if (ctx.inject) {
+    const injectNodes = stringToAST(ctx.inject) as ts.Node[];
+    type.push(...injectNodes);
+  }
+
   for (const root of Object.keys(transformers) as SchemaTransforms[]) {
     const emptyObj = ts.factory.createTypeAliasDeclaration(
       /* modifiers      */ tsModifiers({ export: true }),

packages/openapi-typescript/src/types.ts

@@ -660,6 +660,8 @@ export interface OpenAPITSOptions {
    * @see https://redocly.com/docs/cli/configuration/
    */
   redocly?: RedoclyConfig;
+  /** Inject arbitrary TypeScript types into the start of the file */
+  inject?: string;
 }
 
 /** Context passed to all submodules */
@@ -688,6 +690,7 @@ export interface GlobalContext {
   transform: OpenAPITSOptions["transform"];
   /** retrieve a node by $ref */
   resolve<T>($ref: string): T | undefined;
+  inject?: string;
 }
 
 export type $defs = Record<string, SchemaObject>;

packages/openapi-typescript/test/index.test.ts

@@ -668,6 +668,32 @@ export type operations = Record<string, never>;`,
         // options: DEFAULT_OPTIONS,
       },
     ],
+    [
+      "inject option",
+      {
+        given: {
+          openapi: "3.1",
+          info: { title: "Test", version: "1.0" },
+        },
+        want: `type Foo = string;
+type Bar = number;
+export type paths = Record<string, never>;
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: never;
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export type operations = Record<string, never>;`,
+        options: {
+          inject: "type Foo = string;\ntype Bar = number;",
+        },
+      },
+    ],
   ];
 
   for (const [testName, { given, want, options, ci }] of tests) {