feat: clear $ref fields across entire OpenAPI document

Author: guan404ming

utils/component/openapi_generator.go

@@ -196,17 +196,143 @@ func getResolvedManifest(manifest string) (string, error) {
 	if doc.Components == nil || len(doc.Components.Schemas) == 0 {
 		return "", ErrNoSchemasFound
 	}
-	stack := make(map[*openapi3.Schema]bool)
-	for _, schemaRef := range doc.Components.Schemas {
-		clearSchemaRefs(schemaRef, stack)
-	}
+	clearDocRefs(doc)
 	resolved, err := json.Marshal(doc)
 	if err != nil {
 		return "", err
 	}
 	return string(resolved), nil
 }
 
+// clearDocRefs clears $ref strings across the entire OpenAPI document,
+// including paths, components/parameters, components/headers,
+// components/requestBodies, components/responses, and components/callbacks.
+func clearDocRefs(doc *openapi3.T) {
+	stack := make(map[*openapi3.Schema]bool)
+
+	if doc.Components != nil {
+		for _, sr := range doc.Components.Schemas {
+			clearSchemaRefs(sr, stack)
+		}
+		for _, pr := range doc.Components.Parameters {
+			clearParameterRefs(pr, stack)
+		}
+		for _, hr := range doc.Components.Headers {
+			clearHeaderRefs(hr, stack)
+		}
+		for _, rb := range doc.Components.RequestBodies {
+			clearRequestBodyRefs(rb, stack)
+		}
+		for _, rr := range doc.Components.Responses {
+			clearResponseRefs(rr, stack)
+		}
+		for _, cr := range doc.Components.Callbacks {
+			clearCallbackRefs(cr, stack)
+		}
+	}
+
+	if doc.Paths != nil {
+		for _, pathItem := range doc.Paths.Map() {
+			clearPathItemRefs(pathItem, stack)
+		}
+	}
+}
+
+func clearContentRefs(content openapi3.Content, stack map[*openapi3.Schema]bool) {
+	for _, mt := range content {
+		if mt != nil {
+			clearSchemaRefs(mt.Schema, stack)
+		}
+	}
+}
+
+func clearParameterRefs(pr *openapi3.ParameterRef, stack map[*openapi3.Schema]bool) {
+	if pr == nil {
+		return
+	}
+	pr.Ref = ""
+	if pr.Value != nil {
+		clearSchemaRefs(pr.Value.Schema, stack)
+		clearContentRefs(pr.Value.Content, stack)
+	}
+}
+
+func clearHeaderRefs(hr *openapi3.HeaderRef, stack map[*openapi3.Schema]bool) {
+	if hr == nil {
+		return
+	}
+	hr.Ref = ""
+	if hr.Value != nil {
+		clearSchemaRefs(hr.Value.Schema, stack)
+		clearContentRefs(hr.Value.Content, stack)
+	}
+}
+
+func clearRequestBodyRefs(rb *openapi3.RequestBodyRef, stack map[*openapi3.Schema]bool) {
+	if rb == nil {
+		return
+	}
+	rb.Ref = ""
+	if rb.Value != nil {
+		clearContentRefs(rb.Value.Content, stack)
+	}
+}
+
+func clearResponseRefs(rr *openapi3.ResponseRef, stack map[*openapi3.Schema]bool) {
+	if rr == nil {
+		return
+	}
+	rr.Ref = ""
+	if rr.Value != nil {
+		clearContentRefs(rr.Value.Content, stack)
+		for _, hr := range rr.Value.Headers {
+			clearHeaderRefs(hr, stack)
+		}
+	}
+}
+
+func clearCallbackRefs(cr *openapi3.CallbackRef, stack map[*openapi3.Schema]bool) {
+	if cr == nil {
+		return
+	}
+	cr.Ref = ""
+	if cr.Value != nil {
+		for _, pathItem := range cr.Value.Map() {
+			clearPathItemRefs(pathItem, stack)
+		}
+	}
+}
+
+func clearPathItemRefs(pathItem *openapi3.PathItem, stack map[*openapi3.Schema]bool) {
+	if pathItem == nil {
+		return
+	}
+	for _, pr := range pathItem.Parameters {
+		clearParameterRefs(pr, stack)
+	}
+	for _, op := range pathItem.Operations() {
+		clearOperationRefs(op, stack)
+	}
+}
+
+func clearOperationRefs(op *openapi3.Operation, stack map[*openapi3.Schema]bool) {
+	if op == nil {
+		return
+	}
+	for _, pr := range op.Parameters {
+		clearParameterRefs(pr, stack)
+	}
+	clearRequestBodyRefs(op.RequestBody, stack)
+	if op.Responses != nil {
+		for _, rr := range op.Responses.Map() {
+			clearResponseRefs(rr, stack)
+		}
+	}
+	for _, cr := range op.Callbacks {
+		clearCallbackRefs(cr, stack)
+	}
+}
+
 // clearSchemaRefs recursively clears $ref strings on all nested SchemaRefs
 // so that json.Marshal outputs fully inlined schemas. The stack set tracks
 // Schema values (not SchemaRef pointers) on the current recursion path to

utils/component/openapi_generator_test.go

@@ -370,6 +370,185 @@ func TestClearSchemaRefs_SelfReference(t *testing.T) {
 	}
 }
 
+func TestGetResolvedManifest_PathsAndComponents(t *testing.T) {
+	input := `{
+		"openapi": "3.0.0",
+		"info": {"title": "test", "version": "1.0"},
+		"paths": {
+			"/pets": {
+				"get": {
+					"parameters": [
+						{"$ref": "#/components/parameters/LimitParam"}
+					],
+					"responses": {
+						"200": {
+							"$ref": "#/components/responses/PetList"
+						}
+					}
+				},
+				"post": {
+					"requestBody": {
+						"$ref": "#/components/requestBodies/PetBody"
+					},
+					"responses": {
+						"201": {
+							"description": "created"
+						}
+					}
+				}
+			}
+		},
+		"components": {
+			"schemas": {
+				"Pet": {
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"}
+					}
+				}
+			},
+			"parameters": {
+				"LimitParam": {
+					"name": "limit",
+					"in": "query",
+					"schema": {"type": "integer"}
+				}
+			},
+			"requestBodies": {
+				"PetBody": {
+					"content": {
+						"application/json": {
+							"schema": {"$ref": "#/components/schemas/Pet"}
+						}
+					}
+				}
+			},
+			"responses": {
+				"PetList": {
+					"description": "A list of pets",
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "array",
+								"items": {"$ref": "#/components/schemas/Pet"}
+							}
+						}
+					}
+				}
+			}
+		}
+	}`
+
+	out, err := getResolvedManifest(input)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(out), &parsed); err != nil {
+		t.Fatalf("output is not valid JSON: %v", err)
+	}
+
+	// Verify parameter ref in path is resolved.
+	param := navigatePath(t, parsed, "paths./pets.get.parameters")
+	params, ok := param.([]any)
+	if !ok || len(params) == 0 {
+		t.Fatal("expected parameters array")
+	}
+	pm := params[0].(map[string]any)
+	if _, hasRef := pm["$ref"]; hasRef {
+		t.Error("parameter $ref still present in path")
+	}
+	if pm["name"] != "limit" {
+		t.Errorf("parameter name = %v, want limit", pm["name"])
+	}
+
+	// Verify response ref in path is resolved.
+	resp := navigatePath(t, parsed, "paths./pets.get.responses.200").(map[string]any)
+	if _, hasRef := resp["$ref"]; hasRef {
+		t.Error("response $ref still present in path")
+	}
+	if resp["description"] != "A list of pets" {
+		t.Errorf("response description = %v, want 'A list of pets'", resp["description"])
+	}
+
+	// Verify schema ref inside response content is resolved.
+	items := navigatePath(t, parsed, "paths./pets.get.responses.200.content.application/json.schema.items").(map[string]any)
+	if _, hasRef := items["$ref"]; hasRef {
+		t.Error("schema $ref in response items still present")
+	}
+	if items["type"] != "object" {
+		t.Errorf("items type = %v, want object", items["type"])
+	}
+
+	// Verify requestBody ref in path is resolved.
+	rb := navigatePath(t, parsed, "paths./pets.post.requestBody").(map[string]any)
+	if _, hasRef := rb["$ref"]; hasRef {
+		t.Error("requestBody $ref still present in path")
+	}
+
+	// Verify schema ref inside requestBody content is resolved.
+	rbSchema := navigatePath(t, parsed, "paths./pets.post.requestBody.content.application/json.schema").(map[string]any)
+	if _, hasRef := rbSchema["$ref"]; hasRef {
+		t.Error("schema $ref in requestBody content still present")
+	}
+	if rbSchema["type"] != "object" {
+		t.Errorf("requestBody schema type = %v, want object", rbSchema["type"])
+	}
+}
+
+func TestGetResolvedManifest_HeaderRefs(t *testing.T) {
+	input := `{
+		"openapi": "3.0.0",
+		"info": {"title": "test", "version": "1.0"},
+		"paths": {
+			"/items": {
+				"get": {
+					"responses": {
+						"200": {
+							"description": "OK",
+							"headers": {
+								"X-Rate-Limit": {
+									"$ref": "#/components/headers/RateLimit"
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"components": {
+			"schemas": {
+				"Placeholder": {"type": "string"}
+			},
+			"headers": {
+				"RateLimit": {
+					"schema": {"type": "integer"}
+				}
+			}
+		}
+	}`
+
+	out, err := getResolvedManifest(input)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(out), &parsed); err != nil {
+		t.Fatalf("output is not valid JSON: %v", err)
+	}
+
+	header := navigatePath(t, parsed, "paths./items.get.responses.200.headers.X-Rate-Limit").(map[string]any)
+	if _, hasRef := header["$ref"]; hasRef {
+		t.Error("header $ref still present")
+	}
+	schema := header["schema"].(map[string]any)
+	if schema["type"] != "integer" {
+		t.Errorf("header schema type = %v, want integer", schema["type"])
+	}
+}
+
 // navigatePath walks a dot-separated path through nested maps.
 func navigatePath(t *testing.T, data map[string]any, path string) any {
 	t.Helper()