OpenAPI: Context.GetOrCreateSchemaAsync does not take CircularReferences into count.

[desjoerd]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

When you write a SchemaTransformer which unwraps an object (e.g. OptionalValues) the first thing someone would use is Context.GetOrCreateSchemaAsync with the underlying type as it generates the schema for you and will give a schema which will be either inlined or nested depending on it's metadata. The inner schema which is genrated also goes to it's transformers. This is the cause of this issue.

A references B
B references A

What will happen with Circular references

• Transformer transforms A which wraps B
  • Context.GetOrCreateSchemaAsync(B)
    • B has a property of type A
      • Transformer transforms A which wraps B
        • Context.GetOrCreateSchemaAsync(B)
          • B has a property of type A
            • Transformer transforms A which wraps B
              • etc

See for a repro/workaround desjoerd/OptionalValues#22

Expected Behavior

It should track that it's generating or transforming a type. And give a reference to it instead of going for the "Unresolved" schema.

Steps To Reproduce

See desjoerd/OptionalValues#22

It's hard to create a explainable reproduce.

Exceptions (if any)

No response

.NET Version

.NET 10 RC2

Anything else?

I would like to have a design session around Unresolved Schemas, resolved schemas and schema reference handling if possible, to squash this once and for all! 😊

[desjoerd]

I think this can be solved with the following diff after #64109 is merged. The only thing is it breaks the x-ref-description handling of the XmlCommentTransformers. This probably requires an actual SchemaReferenceTransformer to be supported.

        internal async Task ApplySchemaTransformersAsync(OpenApiDocument? document, IOpenApiSchema schema, Type type, IServiceProvider scopedServiceProvider, IOpenApiSchemaTransformer[] schemaTransformers, ApiParameterDescription? parameterDescription = null, CancellationToken cancellationToken = default)
    {
        if (schemaTransformers.Length == 0)
        {
            return;
        }
        var jsonTypeInfo = _jsonSerializerOptions.GetTypeInfo(type);
        var context = new OpenApiSchemaTransformerContext
        {
            DocumentName = documentName,
            JsonTypeInfo = jsonTypeInfo,
            JsonPropertyInfo = null,
            ParameterDescription = parameterDescription,
            ApplicationServices = scopedServiceProvider,
            Document = document,
            SchemaTransformers = schemaTransformers
        };
        for (var i = 0; i < schemaTransformers.Length; i++)
        {
            // Reset context object to base state before running each transformer.
            var transformer = schemaTransformers[i];
+            var processedSchemaIds = new HashSet<string>();
+            await InnerApplySchemaTransformersAsync(schema, jsonTypeInfo, null, context, transformer, processedSchemaIds, cancellationToken);
        }
    }

    private async Task InnerApplySchemaTransformersAsync(IOpenApiSchema inputSchema,
        JsonTypeInfo jsonTypeInfo,
        JsonPropertyInfo? jsonPropertyInfo,
        OpenApiSchemaTransformerContext context,
        IOpenApiSchemaTransformer transformer,
        HashSet<string> processedSchemaIds,
        CancellationToken cancellationToken = default)
    {
        context.UpdateJsonTypeInfo(jsonTypeInfo, jsonPropertyInfo);
        var schema = UnwrapOpenApiSchema(inputSchema);
+        if (schema.IsComponentizedSchema(out var schemaId))
+        {
+            context = new OpenApiSchemaTransformerContext
+            {
+                DocumentName = context.DocumentName,
+                JsonTypeInfo = context.JsonTypeInfo,
+                JsonPropertyInfo = null,
+                ParameterDescription = null,
+                ApplicationServices = context.ApplicationServices,
+                Document = context.Document,
+                SchemaTransformers = context.SchemaTransformers,
+            };
+            if (!processedSchemaIds.Add(schemaId) || context.Document?.Components?.Schemas?.ContainsKey(schemaId) == true)
+            {
+                // Already transformed this schema
+                return;
+            }
+        }

        await transformer.TransformAsync(schema, context, cancellationToken);
...