Fix form-urlencoded request body code generation

Operations with application/x-www-form-urlencoded request bodies
produced uncompilable code: the SimpleClient referenced undefined
typed body structs and methods because the code generator only
recognized application/json content types.

This change introduces a config-driven ContentTypeMatcher that
determines which content types get typed request body methods,
replacing the hard-coded IsJSON checks. form-urlencoded is now
included in the default content-type list alongside JSON.

For form-encoded bodies, serialization uses a new marshalForm
helper (reflection-based, using json struct tags) instead of
json.Marshal, avoiding a JSON round-trip that would produce
incorrect form encoding.

Key changes:
- Replace RequestBodyDescriptor.IsJSON with GenerateTyped (config-driven)
  and IsFormEncoded (content-type flag)
- Add ContentTypeMatcher to operationGatherer and all Gather*Operations
  call sites
- Add DefaultTypedBody/HasTypedBody to OperationDescriptor so the
  SimpleClient template picks the correct typed body
- Add marshalForm/marshalFormImpl helper template for struct-to-url.Values
  serialization
- Update client, initiator, and simple-client templates to branch on
  IsFormEncoded vs JSON for body serialization

Closes #2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mromaszewicz

experimental/internal/codegen/clientgen.go

@@ -61,6 +61,9 @@ func clientFuncs(schemaIndex map[string]*SchemaDescriptor, modelsPackage *Models
 		"isSimpleOperation":              isSimpleOperation,
 		"simpleOperationSuccessResponse": simpleOperationSuccessResponse,
 		"errorResponseForOperation":      errorResponseForOperation,
+		"defaultTypedBody": func(op *OperationDescriptor) *RequestBodyDescriptor {
+			return op.DefaultTypedBody()
+		},
 		"goTypeForContent": func(content *ResponseContentDescriptor) string {
 			return goTypeForContent(content, schemaIndex, modelsPackage)
 		},
@@ -96,6 +99,11 @@ func isSimpleOperation(op *OperationDescriptor) bool {
 		return false
 	}
 
+	// If the operation has a body, it must have a typed body for the simple client
+	if op.HasBody && !op.HasTypedBody() {
+		return false
+	}
+
 	// Count success responses (2xx or default that could be success)
 	var successResponses []*ResponseDescriptor
 	for _, r := range op.Responses {
@@ -261,7 +269,7 @@ func (g *ClientGenerator) GenerateRequestBodyTypes(ops []*OperationDescriptor) s
 
 	for _, op := range ops {
 		for _, body := range op.Bodies {
-			if !body.IsJSON {
+			if !body.GenerateTyped {
 				continue
 			}
 			// Get the underlying type for this request body

experimental/internal/codegen/clientgen_test.go

@@ -38,7 +38,7 @@ func TestClientGenerator(t *testing.T) {
 	paramTracker := NewParamUsageTracker()
 
 	// Gather operations
-	ops, err := GatherOperations(doc, paramTracker)
+	ops, err := GatherOperations(doc, paramTracker, NewContentTypeMatcher(DefaultContentTypes()))
 	require.NoError(t, err, "Failed to gather operations")
 	require.Len(t, ops, 4, "Expected 4 operations")
 
@@ -80,6 +80,68 @@ func TestClientGenerator(t *testing.T) {
 	require.Contains(t, clientCode, "NewSimpleClient")
 }
 
+func TestClientGenerator_FormEncoded(t *testing.T) {
+	// Read the comprehensive spec which includes form-encoded bodies
+	specPath := "test/files/comprehensive.yaml"
+	specData, err := os.ReadFile(specPath)
+	require.NoError(t, err, "Failed to read comprehensive spec")
+
+	doc, err := libopenapi.NewDocument(specData)
+	require.NoError(t, err, "Failed to parse comprehensive spec")
+
+	contentTypeMatcher := NewContentTypeMatcher(DefaultContentTypes())
+	schemas, err := GatherSchemas(doc, contentTypeMatcher)
+	require.NoError(t, err, "Failed to gather schemas")
+
+	converter := NewNameConverter(NameMangling{}, NameSubstitutions{})
+	contentTypeNamer := NewContentTypeShortNamer(DefaultContentTypeShortNames())
+	ComputeSchemaNames(schemas, converter, contentTypeNamer)
+
+	schemaIndex := make(map[string]*SchemaDescriptor)
+	for _, s := range schemas {
+		schemaIndex[s.Path.String()] = s
+	}
+
+	paramTracker := NewParamUsageTracker()
+	ops, err := GatherOperations(doc, paramTracker, contentTypeMatcher)
+	require.NoError(t, err, "Failed to gather operations")
+
+	// Verify we have an operation with a form-encoded body
+	var hasFormBody bool
+	for _, op := range ops {
+		for _, body := range op.Bodies {
+			if body.IsFormEncoded && body.GenerateTyped {
+				hasFormBody = true
+				break
+			}
+		}
+	}
+	require.True(t, hasFormBody, "Expected at least one operation with a form-encoded typed body")
+
+	// Generate client code
+	gen, err := NewClientGenerator(schemaIndex, true, nil)
+	require.NoError(t, err, "Failed to create client generator")
+
+	clientCode, err := gen.GenerateClient(ops)
+	require.NoError(t, err, "Failed to generate client code")
+
+	t.Logf("Generated client code:\n%s", clientCode)
+
+	// Verify form-encoded body methods reference marshalForm
+	require.Contains(t, clientCode, "marshalForm(body)")
+
+	// Verify we generate the form helper when needed
+	formHelper, err := generateFormHelper(ops)
+	require.NoError(t, err, "Failed to generate form helper")
+	require.NotEmpty(t, formHelper, "Form helper should be generated when form-encoded bodies exist")
+	require.Contains(t, formHelper, "func marshalForm(")
+	require.Contains(t, formHelper, "func marshalFormImpl(")
+	require.Contains(t, formHelper, "reflect.Value")
+
+	// Verify it generates WithFormdataBody method
+	require.Contains(t, clientCode, "WithFormdataBody")
+}
+
 func TestIsSimpleOperation(t *testing.T) {
 	tests := []struct {
 		name     string

experimental/internal/codegen/codegen.go

@@ -100,7 +100,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 		paramTracker := NewParamUsageTracker()
 
 		// Gather operations
-		ops, err := GatherOperations(doc, paramTracker)
+		ops, err := GatherOperations(doc, paramTracker, contentTypeMatcher)
 		if err != nil {
 			return "", fmt.Errorf("gathering operations: %w", err)
 		}
@@ -145,6 +145,18 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 		for _, imp := range paramTracker.GetRequiredImports() {
 			output.AddImport(imp.Path, imp.Alias)
 		}
+
+		// Generate form helper if any operation has form-encoded bodies
+		formHelper, err := generateFormHelper(ops)
+		if err != nil {
+			return "", fmt.Errorf("generating form helper: %w", err)
+		}
+		if formHelper != "" {
+			output.AddType(formHelper)
+			for _, imp := range templates.MarshalFormHelperTemplate.Imports {
+				output.AddImport(imp.Path, imp.Alias)
+			}
+		}
 	}
 
 	// Track whether shared error types have been generated to avoid duplication.
@@ -159,7 +171,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 		paramTracker := NewParamUsageTracker()
 
 		// Gather operations
-		ops, err := GatherOperations(doc, paramTracker)
+		ops, err := GatherOperations(doc, paramTracker, contentTypeMatcher)
 		if err != nil {
 			return "", fmt.Errorf("gathering operations: %w", err)
 		}
@@ -216,7 +228,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 	if cfg.Generation.WebhookInitiator {
 		paramTracker := NewParamUsageTracker()
 
-		webhookOps, err := GatherWebhookOperations(doc, paramTracker)
+		webhookOps, err := GatherWebhookOperations(doc, paramTracker, contentTypeMatcher)
 		if err != nil {
 			return "", fmt.Errorf("gathering webhook operations: %w", err)
 		}
@@ -253,14 +265,26 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 			for _, imp := range paramTracker.GetRequiredImports() {
 				output.AddImport(imp.Path, imp.Alias)
 			}
+
+			// Generate form helper if any webhook operation has form-encoded bodies
+			formHelper, err := generateFormHelper(webhookOps)
+			if err != nil {
+				return "", fmt.Errorf("generating form helper: %w", err)
+			}
+			if formHelper != "" {
+				output.AddType(formHelper)
+				for _, imp := range templates.MarshalFormHelperTemplate.Imports {
+					output.AddImport(imp.Path, imp.Alias)
+				}
+			}
 		}
 	}
 
 	// Generate callback initiator code if requested
 	if cfg.Generation.CallbackInitiator {
 		paramTracker := NewParamUsageTracker()
 
-		callbackOps, err := GatherCallbackOperations(doc, paramTracker)
+		callbackOps, err := GatherCallbackOperations(doc, paramTracker, contentTypeMatcher)
 		if err != nil {
 			return "", fmt.Errorf("gathering callback operations: %w", err)
 		}
@@ -297,6 +321,18 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 			for _, imp := range paramTracker.GetRequiredImports() {
 				output.AddImport(imp.Path, imp.Alias)
 			}
+
+			// Generate form helper if any callback operation has form-encoded bodies
+			formHelper, err := generateFormHelper(callbackOps)
+			if err != nil {
+				return "", fmt.Errorf("generating form helper: %w", err)
+			}
+			if formHelper != "" {
+				output.AddType(formHelper)
+				for _, imp := range templates.MarshalFormHelperTemplate.Imports {
+					output.AddImport(imp.Path, imp.Alias)
+				}
+			}
 		}
 	}
 
@@ -308,7 +344,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 
 		paramTracker := NewParamUsageTracker()
 
-		webhookOps, err := GatherWebhookOperations(doc, paramTracker)
+		webhookOps, err := GatherWebhookOperations(doc, paramTracker, contentTypeMatcher)
 		if err != nil {
 			return "", fmt.Errorf("gathering webhook operations: %w", err)
 		}
@@ -378,7 +414,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 
 		paramTracker := NewParamUsageTracker()
 
-		callbackOps, err := GatherCallbackOperations(doc, paramTracker)
+		callbackOps, err := GatherCallbackOperations(doc, paramTracker, contentTypeMatcher)
 		if err != nil {
 			return "", fmt.Errorf("gathering callback operations: %w", err)
 		}
@@ -442,6 +478,43 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 	return output.Format()
 }
 
+// hasFormEncodedBodies returns true if any operation has a form-encoded typed request body.
+func hasFormEncodedBodies(ops []*OperationDescriptor) bool {
+	for _, op := range ops {
+		for _, body := range op.Bodies {
+			if body.IsFormEncoded && body.GenerateTyped {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// generateFormHelper generates the marshalForm helper function if needed.
+func generateFormHelper(ops []*OperationDescriptor) (string, error) {
+	if !hasFormEncodedBodies(ops) {
+		return "", nil
+	}
+
+	tmplInfo := templates.MarshalFormHelperTemplate
+	content, err := templates.TemplateFS.ReadFile("files/" + tmplInfo.Template)
+	if err != nil {
+		return "", fmt.Errorf("reading form helper template: %w", err)
+	}
+
+	tmpl, err := template.New(tmplInfo.Name).Parse(string(content))
+	if err != nil {
+		return "", fmt.Errorf("parsing form helper template: %w", err)
+	}
+
+	var result strings.Builder
+	if err := tmpl.Execute(&result, nil); err != nil {
+		return "", fmt.Errorf("executing form helper template: %w", err)
+	}
+
+	return result.String(), nil
+}
+
 // generateParamFunctionsFromTracker generates the parameter styling/binding functions based on usage.
 func generateParamFunctionsFromTracker(tracker *ParamUsageTracker) (string, error) {
 	if !tracker.HasAnyUsage() {

experimental/internal/codegen/configuration.go

@@ -152,6 +152,7 @@ func DefaultContentTypes() []string {
 	return []string{
 		`^application/json$`,
 		`^application/.*\+json$`,
+		`^application/x-www-form-urlencoded$`,
 	}
 }
 

experimental/internal/codegen/filter_test.go

@@ -85,7 +85,7 @@ func gatherTestOps(t *testing.T) []*OperationDescriptor {
 	require.NoError(t, err)
 
 	tracker := NewParamUsageTracker()
-	ops, err := GatherOperations(doc, tracker)
+	ops, err := GatherOperations(doc, tracker, NewContentTypeMatcher(DefaultContentTypes()))
 	require.NoError(t, err)
 	return ops
 }

experimental/internal/codegen/gather_operations.go

@@ -11,7 +11,8 @@ import (
 )
 
 // GatherOperations traverses an OpenAPI document and collects all operations.
-func GatherOperations(doc libopenapi.Document, paramTracker *ParamUsageTracker) ([]*OperationDescriptor, error) {
+// contentTypeMatcher determines which content types get typed request body methods.
+func GatherOperations(doc libopenapi.Document, paramTracker *ParamUsageTracker, contentTypeMatcher *ContentTypeMatcher) ([]*OperationDescriptor, error) {
 	model, err := doc.BuildV3Model()
 	if err != nil {
 		return nil, fmt.Errorf("building v3 model: %w", err)
@@ -21,14 +22,16 @@ func GatherOperations(doc libopenapi.Document, paramTracker *ParamUsageTracker)
 	}
 
 	g := &operationGatherer{
-		paramTracker: paramTracker,
+		paramTracker:       paramTracker,
+		contentTypeMatcher: contentTypeMatcher,
 	}
 
 	return g.gatherFromDocument(&model.Model)
 }
 
 type operationGatherer struct {
-	paramTracker *ParamUsageTracker
+	paramTracker       *ParamUsageTracker
+	contentTypeMatcher *ContentTypeMatcher
 }
 
 func (g *operationGatherer) gatherFromDocument(doc *v3.Document) ([]*OperationDescriptor, error) {
@@ -317,16 +320,22 @@ func (g *operationGatherer) gatherRequestBodies(operationID string, bodyRef *v3.
 			bodyRequired = *bodyRef.Required
 		}
 
+		generateTyped := false
+		if g.contentTypeMatcher != nil {
+			generateTyped = g.contentTypeMatcher.Matches(contentType)
+		}
+
 		desc := &RequestBodyDescriptor{
 			ContentType: contentType,
 			Required:    bodyRequired,
 			Schema:      schemaDesc,
 
-			NameTag:    nameTag,
-			GoTypeName: goTypeName,
-			FuncSuffix: funcSuffix,
-			IsDefault:  isDefault,
-			IsJSON:     IsMediaTypeJSON(contentType),
+			NameTag:       nameTag,
+			GoTypeName:    goTypeName,
+			FuncSuffix:    funcSuffix,
+			IsDefault:     isDefault,
+			IsFormEncoded: contentType == "application/x-www-form-urlencoded",
+			GenerateTyped: generateTyped,
 		}
 
 		// Gather encoding options for form data
@@ -568,7 +577,7 @@ func sortPathParamsByPath(path string, params []*ParameterDescriptor) ([]*Parame
 }
 
 // GatherWebhookOperations traverses an OpenAPI document and collects operations from webhooks.
-func GatherWebhookOperations(doc libopenapi.Document, paramTracker *ParamUsageTracker) ([]*OperationDescriptor, error) {
+func GatherWebhookOperations(doc libopenapi.Document, paramTracker *ParamUsageTracker, contentTypeMatcher *ContentTypeMatcher) ([]*OperationDescriptor, error) {
 	model, err := doc.BuildV3Model()
 	if err != nil {
 		return nil, fmt.Errorf("building v3 model: %w", err)
@@ -578,14 +587,15 @@ func GatherWebhookOperations(doc libopenapi.Document, paramTracker *ParamUsageTr
 	}
 
 	g := &operationGatherer{
-		paramTracker: paramTracker,
+		paramTracker:       paramTracker,
+		contentTypeMatcher: contentTypeMatcher,
 	}
 
 	return g.gatherWebhooks(&model.Model)
 }
 
 // GatherCallbackOperations traverses an OpenAPI document and collects operations from callbacks.
-func GatherCallbackOperations(doc libopenapi.Document, paramTracker *ParamUsageTracker) ([]*OperationDescriptor, error) {
+func GatherCallbackOperations(doc libopenapi.Document, paramTracker *ParamUsageTracker, contentTypeMatcher *ContentTypeMatcher) ([]*OperationDescriptor, error) {
 	model, err := doc.BuildV3Model()
 	if err != nil {
 		return nil, fmt.Errorf("building v3 model: %w", err)
@@ -595,7 +605,8 @@ func GatherCallbackOperations(doc libopenapi.Document, paramTracker *ParamUsageT
 	}
 
 	g := &operationGatherer{
-		paramTracker: paramTracker,
+		paramTracker:       paramTracker,
+		contentTypeMatcher: contentTypeMatcher,
 	}
 
 	return g.gatherCallbacks(&model.Model)

experimental/internal/codegen/initiatorgen.go

@@ -132,7 +132,7 @@ func (g *InitiatorGenerator) GenerateRequestBodyTypes(ops []*OperationDescriptor
 
 	for _, op := range ops {
 		for _, body := range op.Bodies {
-			if !body.IsJSON {
+			if !body.GenerateTyped {
 				continue
 			}
 			var targetType string