feat: allow x-zod-schema extension property in openapi docs to override generated schema

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "workbench.colorCustomizations": {
+        "activityBar.background": "#590F2C",
+        "titleBar.activeBackground": "#7D143E",
+        "titleBar.activeForeground": "#FEFCFD"
+    }
+}

lib/src/cli.ts

@@ -52,6 +52,7 @@ cli.command("<input>", "path/url to OpenAPI/Swagger document as json/yaml")
     .option("--all-readonly", "when true, all generated objects and arrays will be readonly")
     .option("--export-types", "When true, will defined types for all object schemas in `#/components/schemas`")
     .option("--additional-props-default-value", "Set default value when additionalProperties is not provided. Default to true.", { default: true })
+    .option('--x-zod-schema', "When true, allows using x-zod-schema property to generate zod schema for a given openapi schema.")
     .action(async (input, options) => {
         console.log("Retrieving OpenAPI document from", input);
         const openApiDoc = (await SwaggerParser.bundle(input)) as OpenAPIObject;
@@ -82,7 +83,8 @@ cli.command("<input>", "path/url to OpenAPI/Swagger document as json/yaml")
                 defaultStatusBehavior: options.defaultStatus,
                 withDescription: options.withDescription,
                 allReadonly: options.allReadonly,
-                additionalPropertiesDefaultValue: options.additionalPropsDefaultValue
+                additionalPropertiesDefaultValue: options.additionalPropsDefaultValue === 'false' ? false : options.additionalPropsDefaultValue,
+                xZodSchema: options.xZodSchema,
             },
         });
         console.log(`Done generating <${distPath}> !`);

lib/src/openApiToTypescript.ts

@@ -94,6 +94,11 @@ TsConversionArgs): ts.Node | TypeDefinitionObject | string => {
             return t.reference(schemaName);
         }
 
+        const xZodSchema = schema["x-zod-schema"];
+        if (Array.isArray(xZodSchema) && xZodSchema.length > 1) {
+            return t.reference(xZodSchema[1]);
+        }
+
         if (Array.isArray(schema.type)) {
             if (schema.type.length === 1) {
                 return getTypescriptFromOpenApi({ schema: { ...schema, type: schema.type[0]! }, ctx, meta, options });

lib/src/openApiToZod.ts

@@ -63,6 +63,16 @@ export function getZodSchema({ schema, ctx, meta: inheritedMeta, options }: Conv
         return code;
     }
 
+    if (options?.xZodSchema) {
+        const xZodSchema = schema["x-zod-schema"];
+        if (Array.isArray(xZodSchema) && xZodSchema.length > 0) {
+            return code.assign(xZodSchema[0]);
+        } else if(typeof xZodSchema === 'string') {
+            return code.assign(xZodSchema);
+        }
+    }
+
+
     if (Array.isArray(schema.type)) {
         if (schema.type.length === 1) {
             return getZodSchema({ schema: { ...schema, type: schema.type[0]! }, ctx, meta, options });
@@ -270,11 +280,14 @@ type ZodChainArgs = { schema: SchemaObject; meta?: CodeMetaData; options?: Templ
 export const getZodChain = ({ schema, meta, options }: ZodChainArgs) => {
     const chains: string[] = [];
 
-    match(schema.type)
+    if(!(options?.xZodSchema && schema["x-zod-schema"])) {
+        // skip schema type-based chains for escape hatch 
+        match(schema.type)
         .with("string", () => chains.push(getZodChainableStringValidations(schema)))
         .with("number", "integer", () => chains.push(getZodChainableNumberValidations(schema)))
         .with("array", () => chains.push(getZodChainableArrayValidations(schema)))
         .otherwise(() => void 0);
+    }
 
     if (typeof schema.description === "string" && schema.description !== "" && options?.withDescription) {
         chains.push(`describe("${schema.description}")`);

lib/src/template-context.ts

@@ -387,4 +387,9 @@ export type TemplateContextOptions = {
      * When true, returns a "responses" array with all responses (both success and errors)
      */
     withAllResponses?: boolean;
+
+    /**
+     * When true, supports `x-zod-schema` to define the complete zod schema for a given openapi schema. 
+     */
+    xZodSchema?: boolean;
 };