[9.0-preview7] Response schema being returned as IResult

[martincostello]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Updating from version 9.0.0-preview.7.24372.9 to 9.0.0-preview.7.24373.9 of Microsoft.AspNetCore.OpenApi, [ProducesResponseType] seems to have stopped working and instead of the correct response type for an API endpoint, IResult is returned instead.

Here's the document:

{
  "openapi": "3.0.1",
  "info": {
    "title": "London Travel",
    "description": "London Travel is an Amazon Alexa skill for checking the status for travel in London.",
    "termsOfService": "https://londontravel.martincostello.com/terms-of-service/",
    "contact": {
      "name": "Martin Costello",
      "url": "https://github.com/martincostello/alexa-london-travel-site"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": ""
  },
  "servers": [
    {
      "url": "https://localhost"
    }
  ],
  "paths": {
    "/api/preferences": {
      "get": {
        "tags": [
          "LondonTravel.Site"
        ],
        "summary": "Gets a user's preferences.",
        "description": "Gets the preferences for a user associated with an access token.",
        "operationId": "GetApiPreferences",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization header.",
            "schema": {
              "type": "string",
              "nullable": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The preferences associated with the provided access token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IResult"
                }
              }
            }
          },
          "401": {
            "description": "A valid access token was not provided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "statusCode": 401,
                  "message": "Unauthorized.",
                  "requestId": "0HKT0TM6UJASI",
                  "details": [
                    "Only the Bearer authorization scheme is supported."
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "required": [
          "statusCode",
          "message",
          "requestId",
          "details"
        ],
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "description": "The HTTP status code.",
            "format": "int32"
          },
          "message": {
            "type": "string",
            "description": "The error message."
          },
          "requestId": {
            "type": "string",
            "description": "The request Id."
          },
          "details": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The error details, if any."
          }
        },
        "description": "Represents an error from an API resource."
      },
      "IResult": {
        "type": "object"
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "description": "Access token authentication using a bearer token.",
        "scheme": "bearer",
        "bearerFormat": "Opaque token"
      }
    }
  },
  "security": [
    {
      "Bearer": [ ]
    }
  ],
  "tags": [
    {
      "name": "LondonTravel.Site"
    }
  ]
}

Expected Behavior

A schema for PreferencesResponse should be returned.

Steps To Reproduce

1. Clone martincostello/alexa-london-travel-site@2a6df23
2. Start the app
3. Browser the OpenAPI document returned by /openapi/api.json

Exceptions (if any)

No response

.NET Version

9.0.100-preview.7.24374.2

Anything else?

No response

[martincostello]

I have another application returning HTTP 500 errors when requesting the OpenAPI document. It's an internal codebase so I can't share a link to the repo, but it looks like a similar issue with the endpoint method's return type trying to be serialized instead of the actual schema.

This is the stack trace I get when running the application when published with native AoT:

 System.NotSupportedException: JsonTypeInfo metadata for type 'Microsoft.AspNetCore.Http.HttpResults.Results`2[Microsoft.AspNetCore.Http.HttpResults.JsonHttpResult`1[JustEatTakeaway.RuntimeSupportScout.Models.DotNetRuntimes],Microsoft.AspNetCore.Http.HttpResults.ProblemHttpResult]' was not provided by TypeInfoResolver of type 'System.Text.Json.Serialization.Metadata.JsonTypeInfoResolverWithAddedModifiers'. If using source generation, ensure that all root types passed to the serializer have been annotated with 'JsonSerializableAttribute', along with any types that might be serialized polymorphically.
         at System.Text.Json.ThrowHelper.ThrowNotSupportedException_NoMetadataForType(Type type, IJsonTypeInfoResolver resolver)
         at System.Text.Json.JsonSerializerOptions.GetTypeInfoInternal(Type type, Boolean ensureConfigured, Nullable`1 ensureNotNull, Boolean resolveIfMutable, Boolean fallBackToNearestAncestorType)
         at System.Text.Json.Schema.JsonSchemaExporter.GetJsonSchemaAsNode(JsonSerializerOptions options, Type type, JsonSchemaExporterOptions exporterOptions)
         at Microsoft.AspNetCore.OpenApi.OpenApiSchemaService.CreateSchema(OpenApiSchemaKey key)

It looks like Microsoft.AspNetCore.Http.HttpResults.Results<T1, T2> is trying to be serialized instead of the appropriate T1/T2.

[martincostello]

Looking at the commit history for OpenApi, I think the regression must be from #56937.

[captainsafia]

Thanks as always for the speedy bug report, @martincostello!

WRT to the instance you're able to report publicly, I think this is something better tests would've helped us catch. We'll need a variant of this test that uses an awaitable return type.

The second one is a bit more interesting since it looks like you're using the Results<T1, ..., TN> return type. I tried to write a test to repro this behavior but didn't have any luck (see below). Do you happen to be using an awaitable type in this endpoint as well?

[Fact]
public void AddsMultipleResponseFormatsForTypedResults()
{
    var apiDescription = GetApiDescription(Results<Created<InferredJsonClass>, BadRequest> () =>
        TypedResults.Created("https://example.com", new InferredJsonClass()));

    Assert.Equal(2, apiDescription.SupportedResponseTypes.Count);

    var createdResponseType = apiDescription.SupportedResponseTypes[0];

    Assert.Equal(201, createdResponseType.StatusCode);
    Assert.Equal(typeof(InferredJsonClass), createdResponseType.Type);
    Assert.Equal(typeof(InferredJsonClass), createdResponseType.ModelMetadata?.ModelType);

    var createdResponseFormat = Assert.Single(createdResponseType.ApiResponseFormats);
    Assert.Equal("application/json", createdResponseFormat.MediaType);

    var badRequestResponseType = apiDescription.SupportedResponseTypes[1];

    Assert.Equal(400, badRequestResponseType.StatusCode);
    Assert.Equal(typeof(void), badRequestResponseType.Type);
    Assert.Equal(typeof(void), badRequestResponseType.ModelMetadata?.ModelType);

    Assert.Empty(badRequestResponseType.ApiResponseFormats);
}

[martincostello]

I would imagine so as the implementation is doing an async call to an API.

I'll try and extract out the method signature for you tomorrow when I'm back on my work laptop.

[martincostello]

Here's the relevant method signatures:

public static IEndpointRouteBuilder MapDomainEndpoints(this IEndpointRouteBuilder endpoints)
{
    var runtimes = endpoints.MapGroup("/runtimes")
                            .WithTags("runtimes");

    runtimes.MapGet("dotnet", GetDotNetRuntimes)
            .WithName("dotnet-runtimes")
            .WithSummary("Get .NET versions")
            .WithDescription("Gets all of the known .NET runtime versions.");

    return endpoints;
}

[ProducesResponseType<DotNetRuntimes>(StatusCodes.Status200OK)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status500InternalServerError, "application/problem+json")]
private static async Task<Results<JsonHttpResult<DotNetRuntimes>, ProblemHttpResult>> GetDotNetRuntimes(
    [FromServices] DotNetRuntimeService service,
    CancellationToken cancellationToken)
{
    var runtimes = await service.GetAsync(cancellationToken);
    return TypedResults.Json(runtimes, AppJsonSerializerContext.Default.DotNetRuntimes);
}

[martincostello]

I did some refactoring on the application in the main description, and the problem has gone away.

The relevant change was removed the [ProducesResponseType<T>] attributes on the handler method itself and instead added Produces<T>() calls to the endpoint:

endpoint.Map(/* etc. */)
        .Produces<PreferencesResponse>(StatusCodes.Status200OK)
        .Produces<ErrorResponse>(StatusCodes.Status401Unauthorized);

I guess something's going awry with getting the attributes off the method compared to looking at the endpoint metadata.

[captainsafia]

I guess something's going awry with getting the attributes off the method compared to looking at the endpoint metadata.

I can share some insights on this. Although the ProducesResponseType attribute and the Produces extension method are intended to replicate the same behavior, the underlying implementation is slightly different.

The ProducesResponseType attributes is an MVC concept that influences what metadata is generated in ApiExplorer and plays a role in MVC's content negotiation layer. It does not implement the IProducesResponseTypeMetadata interface and there is special code in minimal API's ApiExplorer implementation to support it. Support for this attributes predates the Produces extension method and metadata.

The Produces extension method adds a metadata element to the endpoint's metadata collection that implements the IProducesResponseTypeMetadata interface. The code for supporting this in ApiExplorer is a little bit more straightforward.

Generally, we prefer the metadata approach (via extension methods like Produces or via IEndpointMetadataProvider implementations) because it is more straightforward.

However, some people still prefer attributes (hence the reason for the back-compat here) so this bug is suspicious.

Given that the test sample I used above uses metadata this would confirm the behavior that you are seeing around this bug only manifesting for attribute scenarios. This is still sus to me and I want to figure out why it's happening but it's good to know there's a viable workaround for now.