fix(cli): fix endpoint example generation for global headers, nullable params, and recursive types (#12342)

* fix(cli): skip global header example failures instead of dropping all endpoint examples

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

* Handle nullable/optional examples and stub cycles

Traverse nullable/optional wrappers when checking for examples and generate minimal stub examples on recursive cycle detection. ExampleTypeFactory.hasExample now recurses into nullable/optional containers so examples (e.g. nullable query params) are not dropped during OpenAPI parsing. The v1 example generator (generateTypeReferenceExample) returns a minimal filled stub for named types when recursion is detected instead of failing, filling only leaf properties (primitives/enums/literals) to avoid cascade failures. Tests were updated/extended to reflect the new behavior (including a BulkSchedule-like 3-way cycle), and versions.yml was bumped with a changelog entry describing the fixes. Minor imports were adjusted to support the new helper functions.

* Reformat object literals in example generator

Adjust formatting in packages/commons/ir-utils/src/examples/v1/generateTypeReferenceExample.ts: expand inline object literals into multi-line form for the alias shape and the failure return values in recursive union and undiscriminated union cases. This is a whitespace/formatting change only to improve readability; no logic was modified.

* Update v3 SDK snapshot for TreeNode examples

Refresh test snapshot to match new generated examples and shapes for the v3 SDK. Changes include an updated example id, expanded jsonExample values (adding left/right empty objects), and richer type/shape metadata for the TreeNode optional/container fields (including empty jsonExample placeholders and named type details). This is a snapshot-only update under packages/cli/api-importers/v3-importer-tests/src/__test__/__snapshots__/v3-sdks/example-depth.json.

* fix: update simple-fhir IR snapshot for cycle detection stub examples

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

* fix: consolidate changelog entries into single 3.78.1 version

Co-Authored-By: naman.anand@buildwithfern.com <iamnamananand996@gmail.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Naman Anand <info@buildwithfern.com>

Author: 3 people

packages/cli/api-importers/openapi/openapi-ir-parser/src/openapi/v3/converters/ExampleEndpointFactory.ts

@@ -594,9 +594,7 @@ export class ExampleEndpointFactory {
                 );
                 example = undefined;
             }
-            if (example == null) {
-                return [];
-            } else if (example != null) {
+            if (example != null) {
                 headers.push({
                     name: globalHeader.header,
                     value: example

packages/cli/api-importers/openapi/openapi-ir-parser/src/schema/examples/ExampleTypeFactory.ts

@@ -788,6 +788,9 @@ export class ExampleTypeFactory {
             }
             case "unknown":
                 return schema.example != null;
+            case "nullable":
+            case "optional":
+                return this.hasExample(schema.value, depth, visitedSchemaIds, options);
             case "oneOf":
                 return Object.values(schema.value.schemas).some((schema) =>
                     this.hasExample(schema, depth, visitedSchemaIds, options)

packages/cli/api-importers/v3-importer-tests/src/__test__/__snapshots__/v3-sdks/example-depth.json

@@ -6,6 +6,16 @@
       type: feat
   createdAt: "2026-02-14"
   irVersion: 65
+- version: 3.78.1
+  changelogEntry:
+    - summary: |
+        Fix endpoint example generation for global headers, nullable params, and recursive types.
+        Global header example failures no longer drop all endpoint examples. Nullable/optional
+        wrappers are now traversed in `hasExample()`. Recursive types produce minimal stub examples
+        on cycle detection instead of cascading failures.
+      type: fix
+  createdAt: "2026-02-13"
+  irVersion: 65
 - version: 3.78.0
   changelogEntry:
     - summary: |

packages/cli/cli/versions.yml

@@ -109,7 +109,7 @@ describe("v1 cycle detection in generateTypeReferenceExample", () => {
         }
     });
 
-    it("should return failure when all required properties are recursive", () => {
+    it("should generate stub when all required properties are recursive", () => {
         const typeDeclarations: Record<TypeId, TypeDeclaration> = {
             AllRequired: makeObjectTypeDeclaration("AllRequired", ["self"], [namedRef("AllRequired")])
         };
@@ -123,7 +123,19 @@ describe("v1 cycle detection in generateTypeReferenceExample", () => {
             skipOptionalProperties: false
         });
 
-        expect(result.type).toBe("failure");
+        // Now succeeds: first visit generates the object, inner "self" property
+        // hits cycle limit and gets a stub empty object instead of failing.
+        // The stub itself is an object with a "self" property that is also a stub.
+        expect(result.type).toBe("success");
+        if (result.type === "success") {
+            const json = result.jsonExample as Record<string, unknown>;
+            expect(json).toHaveProperty("self");
+            const inner = json.self as Record<string, unknown>;
+            // The inner stub also has "self" because it recursed one more level
+            // before hitting the limit. At the deepest level, "self" is an empty stub.
+            expect(inner).toHaveProperty("self");
+            expect(inner.self).toEqual({});
+        }
     });
 
     it("should detect triangle cycle (A -> B -> C -> A) with optional back-edge", () => {
@@ -161,7 +173,9 @@ describe("v1 cycle detection in generateTypeReferenceExample", () => {
             expect(toB2).toHaveProperty("toC");
             const toC2 = toB2.toC as Record<string, unknown>;
             expect(toC2).toHaveProperty("value");
-            expect(toC2.toA).toBeUndefined();
+            // toA gets a stub with leaf properties filled in (value is a string primitive)
+            // but recursive properties (toB) are skipped
+            expect(toC2.toA).toEqual({ value: "value" });
         }
     });
 
@@ -188,6 +202,58 @@ describe("v1 cycle detection in generateTypeReferenceExample", () => {
         }
     });
 
+    it("should generate stubs for 3-way cycle with required fields (BulkSchedule-like)", () => {
+        // Simulates: BulkSchedule -> multi(optional) -> MultiConfig -> schedules(required list) -> ItemSchedule -> schedule(required) -> BulkSchedule
+        const enumRef = (): TypeReference =>
+            TypeReference.primitive({
+                v1: "STRING",
+                v2: PrimitiveTypeV2.string({ default: undefined, validation: undefined })
+            });
+        const listRef = (typeId: string): TypeReference =>
+            TypeReference.container(ContainerType.list(namedRef(typeId)));
+
+        const typeDeclarations: Record<TypeId, TypeDeclaration> = {
+            BulkSchedule: makeObjectTypeDeclaration(
+                "BulkSchedule",
+                ["frequency", "multi"],
+                [enumRef(), optionalNamedRef("MultiConfig")]
+            ),
+            MultiConfig: makeObjectTypeDeclaration("MultiConfig", ["schedules"], [listRef("ItemSchedule")]),
+            ItemSchedule: makeObjectTypeDeclaration(
+                "ItemSchedule",
+                ["item", "schedule"],
+                [enumRef(), namedRef("BulkSchedule")]
+            )
+        };
+
+        const result = generateTypeReferenceExample({
+            fieldName: undefined,
+            typeReference: namedRef("BulkSchedule"),
+            typeDeclarations,
+            maxDepth: 10,
+            currentDepth: 0,
+            skipOptionalProperties: false
+        });
+
+        expect(result.type).toBe("success");
+        if (result.type === "success") {
+            const json = result.jsonExample as Record<string, unknown>;
+            expect(json).toHaveProperty("frequency");
+            expect(json).toHaveProperty("multi");
+            const multi = json.multi as Record<string, unknown>;
+            expect(multi).toHaveProperty("schedules");
+            const schedules = multi.schedules as Array<Record<string, unknown>>;
+            // The list should have items (not be empty) because ItemSchedule.schedule
+            // now gets a stub with leaf properties instead of failing
+            expect(schedules.length).toBeGreaterThan(0);
+            expect(schedules[0]).toHaveProperty("item");
+            expect(schedules[0]).toHaveProperty("schedule");
+            // The stub for BulkSchedule at cycle limit includes its leaf property "frequency"
+            const stubSchedule = schedules[0]?.schedule as Record<string, unknown>;
+            expect(stubSchedule).toHaveProperty("frequency");
+        }
+    });
+
     it("should complete in O(N) time for N optional self-referencing fields, not O(N^N)", () => {
         const fieldCounts = [5, 10, 20, 50];
         const times: number[] = [];

packages/cli/generation/ir-generator-tests/src/ir/__test__/test-definitions/simple-fhir.json

@@ -1,6 +1,9 @@
 import {
+    ExampleObjectProperty,
     ExampleTypeReference,
     ExampleTypeReferenceShape,
+    ExampleTypeShape,
+    FernIr,
     TypeDeclaration,
     TypeId,
     TypeReference
@@ -48,7 +51,7 @@ export function generateTypeReferenceExample({
             const visited = visitedTypes ?? new Map<string, number>();
             const count = visited.get(typeReference.typeId) ?? 0;
             if (count >= 2) {
-                return { type: "failure", message: `Detected recursive type ${typeReference.typeId}` };
+                return generateMinimalNamedExample({ typeDeclaration, typeDeclarations });
             }
             visited.set(typeReference.typeId, count + 1);
             const generatedExample = generateTypeDeclarationExample({
@@ -145,3 +148,201 @@ export function generateTypeReferenceExample({
         }
     }
 }
+
+/**
+ * Checks whether a type reference is a "leaf" — i.e. it can be generated
+ * without recursing into named object/union types that might cycle.
+ * Leaf types: primitives, enums, literals, unknown, and optional/nullable wrappers of leaves.
+ */
+function isLeafTypeReference(typeRef: TypeReference, typeDeclarations: Record<TypeId, TypeDeclaration>): boolean {
+    switch (typeRef.type) {
+        case "primitive":
+        case "unknown":
+            return true;
+        case "named": {
+            const td = typeDeclarations[typeRef.typeId];
+            return td?.shape.type === "enum";
+        }
+        case "container": {
+            switch (typeRef.container.type) {
+                case "literal":
+                    return true;
+                case "optional":
+                    return isLeafTypeReference(typeRef.container.optional, typeDeclarations);
+                case "nullable":
+                    return isLeafTypeReference(typeRef.container.nullable, typeDeclarations);
+                default:
+                    return false;
+            }
+        }
+    }
+}
+
+/**
+ * Generates a stub example for a named type when cycle detection triggers.
+ * Instead of returning failure (which cascades up and kills parent examples),
+ * this produces a valid example with all leaf (non-recursive) properties filled in:
+ * - Objects → generates all primitive/enum/literal properties, skips recursive ones
+ * - Enums → first enum value
+ * - Aliases → resolve non-recursive targets; recursive ones get empty object
+ * - Unions → first noProperties variant if available; otherwise failure
+ */
+function generateMinimalNamedExample({
+    typeDeclaration,
+    typeDeclarations
+}: {
+    typeDeclaration: TypeDeclaration;
+    typeDeclarations: Record<TypeId, TypeDeclaration>;
+}): ExampleGenerationResult<ExampleTypeReference> {
+    switch (typeDeclaration.shape.type) {
+        case "object": {
+            const jsonExample: Record<string, unknown> = {};
+            const properties: ExampleObjectProperty[] = [];
+            for (const property of [
+                ...(typeDeclaration.shape.properties ?? []),
+                ...(typeDeclaration.shape.extendedProperties ?? [])
+            ]) {
+                if (!isLeafTypeReference(property.valueType, typeDeclarations)) {
+                    continue;
+                }
+                const propertyExample = generateTypeReferenceExample({
+                    fieldName: property.name.wireValue,
+                    typeReference: property.valueType,
+                    typeDeclarations,
+                    currentDepth: 0,
+                    maxDepth: 3,
+                    skipOptionalProperties: true
+                });
+                if (propertyExample.type === "failure") {
+                    continue;
+                }
+                properties.push({
+                    name: property.name,
+                    originalTypeDeclaration: typeDeclaration.name,
+                    value: propertyExample.example,
+                    propertyAccess: property.propertyAccess
+                });
+                jsonExample[property.name.wireValue] = propertyExample.jsonExample;
+            }
+            const example = ExampleTypeShape.object({
+                properties,
+                extraProperties: undefined
+            });
+            return {
+                type: "success",
+                example: {
+                    jsonExample,
+                    shape: ExampleTypeReferenceShape.named({
+                        shape: example,
+                        typeName: typeDeclaration.name
+                    })
+                },
+                jsonExample
+            };
+        }
+        case "enum": {
+            const enumValue = typeDeclaration.shape.values[0];
+            if (enumValue == null) {
+                return { type: "failure", message: "No enum values present for recursive type stub" };
+            }
+            const jsonExample = enumValue.name.wireValue;
+            const example = ExampleTypeShape.enum({ value: enumValue.name });
+            return {
+                type: "success",
+                example: {
+                    jsonExample,
+                    shape: ExampleTypeReferenceShape.named({
+                        shape: example,
+                        typeName: typeDeclaration.name
+                    })
+                },
+                jsonExample
+            };
+        }
+        case "alias": {
+            const aliasOf = typeDeclaration.shape.aliasOf;
+            if (aliasOf.type === "primitive") {
+                const { jsonExample, example } = generatePrimitiveExample({
+                    fieldName: undefined,
+                    primitiveType: aliasOf.primitive
+                });
+                return {
+                    type: "success",
+                    example: {
+                        jsonExample,
+                        shape: ExampleTypeReferenceShape.named({
+                            shape: ExampleTypeShape.alias({
+                                value: { jsonExample, shape: ExampleTypeReferenceShape.primitive(example) }
+                            }),
+                            typeName: typeDeclaration.name
+                        })
+                    },
+                    jsonExample
+                };
+            }
+            if (aliasOf.type === "named") {
+                const aliasedDeclaration = typeDeclarations[aliasOf.typeId];
+                if (aliasedDeclaration != null && aliasedDeclaration.name.typeId !== typeDeclaration.name.typeId) {
+                    return generateMinimalNamedExample({ typeDeclaration: aliasedDeclaration, typeDeclarations });
+                }
+            }
+            const jsonExample = {};
+            return {
+                type: "success",
+                example: {
+                    jsonExample,
+                    shape: ExampleTypeReferenceShape.named({
+                        shape: ExampleTypeShape.alias({
+                            value: { jsonExample, shape: ExampleTypeReferenceShape.unknown(jsonExample) }
+                        }),
+                        typeName: typeDeclaration.name
+                    })
+                },
+                jsonExample
+            };
+        }
+        case "union": {
+            const discriminant = typeDeclaration.shape.discriminant;
+            for (const variant of typeDeclaration.shape.types) {
+                const isNoProperties = variant.shape._visit<boolean>({
+                    noProperties: () => true,
+                    samePropertiesAsObject: () => false,
+                    singleProperty: () => false,
+                    _other: () => false
+                });
+                if (isNoProperties) {
+                    const jsonExample = { [discriminant.wireValue]: variant.discriminantValue.wireValue };
+                    return {
+                        type: "success",
+                        example: {
+                            jsonExample,
+                            shape: ExampleTypeReferenceShape.named({
+                                shape: ExampleTypeShape.union({
+                                    discriminant,
+                                    singleUnionType: {
+                                        wireDiscriminantValue: variant.discriminantValue,
+                                        shape: FernIr.ExampleSingleUnionTypeProperties.noProperties()
+                                    },
+                                    baseProperties: [],
+                                    extendProperties: []
+                                }),
+                                typeName: typeDeclaration.name
+                            })
+                        },
+                        jsonExample
+                    };
+                }
+            }
+            return {
+                type: "failure",
+                message: `No simple variant available for recursive union ${typeDeclaration.name.typeId}`
+            };
+        }
+        case "undiscriminatedUnion": {
+            return {
+                type: "failure",
+                message: `Cannot generate stub for recursive undiscriminated union ${typeDeclaration.name.typeId}`
+            };
+        }
+    }
+}