Resolve relative JSON schema references in root schema

[captainsafia]

Closes #61194.

This PR fixes a host of issues with generic types or types that appear multiple times in the type hierarchy by fully resolving the relative references in schemas that are generated by JsonSchemaExporter to inlined schemas to avoid generating invalid refs.

Before (Unresolved References)

  {
    "type": "object",
    "properties": {
      "parent": {
        "$ref": "#/properties/parent/properties/tags"
      },
      "items": {
        "type": "array",
        "items": {
          "$ref": "#/properties/items/items"
        }
      }
    }
  }

After (Resolved References)

  {
    "type": "object",
    "properties": {
      "parent": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer",
              "nullable": true
            },
            "lang": {
              "type": "string",
              "nullable": true
            }
          }
        }
      }
    }
  }

[Copilot]

Pull Request Overview

This PR fixes issues with relative JSON schema references in the OpenAPI schema generation. It resolves problems where generic types or types appearing multiple times in hierarchies generated invalid references by fully resolving relative references to inlined schemas.

Key Changes

• Added reference resolution logic to expand relative $ref paths to their actual schema content
• Updated test expectations to verify proper schema references instead of invalid relative paths
• Added comprehensive test coverage for generic types, reused types across hierarchies, and nullable reference types

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
OpenApiSchemaService.cs	Implements reference resolution with recursive traversal and cycle detection
OpenApiConstants.cs	Adds constants for $ref keyword and fragment prefix
MapSchemasEndpoints.cs	Adds sample endpoints and model classes for testing reference resolution scenarios
OpenApiSchemaReferenceTransformerTests.cs	Adds new test methods and updates existing assertions for resolved references
Snapshot files (3 files)	Updates test output expectations to reflect resolved schemas instead of invalid references

[martincostello]

If you pull #63095 into this branch, do the two failing tests now pass?

[martincostello]

Does this need something to stop an infinite loop happening? IIRC, there's other bits of the code that do recursion that do something like "this is the 64th time I'm calling this, so that's too much - stop".

[captainsafia]

For handling recursion, we rely on things being caught by JsonSchemaExporter before the schema is returned to us. Tests like ThrowsForOverlyNestedSchemas and SupportsDeeplyNestedSchemaWithConfiguredMaxDepth cover this. I don't think there's any new recursion issues that get introduced here and the logic for tracking visited refs is probably sufficient for this scenario?

[captainsafia]

If you pull #63095 into this branch, do the two failing tests now pass?

OpenApiDocumentReferencesAreValid passes. OpenApiDocumentIsValid fails because of the path issue that you're fixing in that PR (thanks!)