Preserve typed property when allOf branches overlap (#84)

Author: cubahno

pkg/codegen/schema_merge.go

@@ -713,18 +713,34 @@ func mergeOpenapiSchemas(s1, s2 *base.Schema) (*base.Schema, error) {
 	// Required. We merge these.
 	result.Required = append(s1.Required, s2.Required...)
 
-	// We merge all properties
+	// We merge all properties. When both schemas declare a property
+	// with the same name, an annotation-only override (carrying only
+	// fields like `example` or `description`) must not overwrite a
+	// sibling that actually shapes the Go type. Otherwise we keep the
+	// previous "s2 wins" behavior, since both sides genuinely shape
+	// the type and the second declaration is the more specific one in
+	// an allOf chain.
+	//
+	// We deliberately pick one of the original SchemaProxies rather
+	// than fabricating a merged proxy via CreateSchemaProxy: downstream
+	// code reads GoLow().GetReference() to attribute properties back to
+	// the spec, and a synthetic proxy has no low-level backing.
 	for k, v := range s1.Properties.FromOldest() {
 		if result.Properties == nil {
 			result.Properties = orderedmap.New[string, *base.SchemaProxy]()
 		}
 		result.Properties.Set(k, v)
 	}
 	for k, v := range s2.Properties.FromOldest() {
-		// TODO: detect conflicts
 		if result.Properties == nil {
 			result.Properties = orderedmap.New[string, *base.SchemaProxy]()
 		}
+
+		if existing, exists := result.Properties.Get(k); exists {
+			if isAnnotationOnlySchema(v.Schema()) && !isAnnotationOnlySchema(existing.Schema()) {
+				continue
+			}
+		}
 		result.Properties.Set(k, v)
 	}
 
@@ -791,6 +807,45 @@ func getSchemaType(schema *base.Schema) []string {
 	return nil
 }
 
+// isAnnotationOnlySchema reports whether a schema has no fields that
+// influence the generated Go type. Schemas like `{ example: cancelled }`
+// or `{ description: "..." }` are annotation-only and must not be
+// allowed to overwrite a sibling declaration that actually carries a
+// type, enum, or sub-schema in an allOf merge.
+func isAnnotationOnlySchema(s *base.Schema) bool {
+	if s == nil {
+		return true
+	}
+	if len(s.Type) > 0 {
+		return false
+	}
+	if len(s.AllOf) > 0 || len(s.OneOf) > 0 || len(s.AnyOf) > 0 {
+		return false
+	}
+	if s.If != nil || s.Then != nil || s.Else != nil || s.Not != nil {
+		return false
+	}
+	if s.Properties != nil && s.Properties.Len() > 0 {
+		return false
+	}
+	if s.PatternProperties != nil && s.PatternProperties.Len() > 0 {
+		return false
+	}
+	if s.Items != nil {
+		return false
+	}
+	if len(s.Enum) > 0 {
+		return false
+	}
+	if s.AdditionalProperties != nil {
+		return false
+	}
+	if s.Const != nil {
+		return false
+	}
+	return true
+}
+
 // mergeNullable merges two nullable pointers using a union (more permissive) approach.
 // If either is true, the result is true. If both are false or nil, the result is nil.
 // This allows merging schemas where one specifies nullable and another doesn't.

pkg/codegen/schema_merge_test.go

@@ -119,6 +119,35 @@ func TestMergeOpenapiSchemas(t *testing.T) {
 		assert.NotEmpty(t, code)
 	})
 
+	t.Run("overlapping property keeps typed declaration", func(t *testing.T) {
+		// When two allOf branches declare the same property and only
+		// one of them gives it a type (the other only attaches an
+		// annotation such as `example`), the typed declaration must
+		// survive the merge. Previously the second branch silently
+		// overwrote the first, turning a `status: string` into an
+		// empty struct.
+		contents, err := os.ReadFile("testdata/merge-overlapping-property-typed-wins.yml")
+		require.NoError(t, err)
+
+		opts := Configuration{
+			PackageName: "testpkg",
+			Output: &Output{
+				UseSingleFile: true,
+			},
+		}
+
+		code, err := Generate(contents, opts)
+		require.NoError(t, err)
+		combined := code.GetCombined()
+
+		assert.Contains(t, combined, "type InvoiceCancellation struct",
+			"InvoiceCancellation should be a struct")
+		assert.Regexp(t, `(?m)Status\s+\*?string`, combined,
+			"Status should keep the string type from the referenced Invoice schema, not collapse to an empty struct from the annotation-only override")
+		assert.NotRegexp(t, `(?m)Status\s+\*?struct\{\}`, combined,
+			"Status must not be generated as struct{}; that would mean the annotation-only override dropped the typed declaration")
+	})
+
 	t.Run("allOf with sibling properties preserves all fields", func(t *testing.T) {
 		contents, err := os.ReadFile("testdata/allof-with-sibling-properties.yml")
 		require.NoError(t, err)

pkg/codegen/testdata/merge-overlapping-property-typed-wins.yml

@@ -0,0 +1,34 @@
+openapi: 3.0.0
+info:
+  title: Overlapping property in allOf preserves the typed declaration
+  version: 1.0.0
+paths:
+  /test:
+    get:
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InvoiceCancellation'
+components:
+  schemas:
+    Invoice:
+      type: object
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+          enum:
+            - open
+            - paid
+            - cancelled
+    InvoiceCancellation:
+      allOf:
+        - $ref: '#/components/schemas/Invoice'
+        - type: object
+          properties:
+            status:
+              example: cancelled