Support multiple response types with the same status code in ApiExplorer

[keahpeters]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

When using the ProducesResponseType attribute to specify multiple response types with the same status code only the last specified status code will be exposed. This limitation affects scenarios where an endpoint might return different types for the same HTTP status code based on business logic. For example in the following the Foo type would not be included in the response metadata.

[HttpGet]
[ProducesResponseType(typeof(Foo), 200)] // This gets ignored
[ProducesResponseType(typeof(Bar), 200)]
public IActionResult Get(bool foo)
{
    if (foo)
    {
        return Ok(new Foo());
    }

    return Ok(new Bar());
}

This is due to the status code being used as the key in the results dictionary when reading the response metadata https://github.com/dotnet/aspnetcore/blob/main/src/Mvc/Mvc.ApiExplorer/src/ApiResponseTypeProvider.cs#L210.

Describe the solution you'd like

All specified response types to be included in SupportedResponseTypes when there are multiple response types with the same status code.

Additional context

Related to domaindrivendev/Swashbuckle.AspNetCore#2743.

[amcasey]

FYI @captainsafia

[captainsafia]

@keahpeters Thanks for reporting this issue!

I'll take a look at the feasibility of making a change to ApiResponseProvider, considering that OpenApi now supports oneOf to represent unions of types. We'll have to approach this area with caution given it hasn't changed much and this modification would be considered a breaking behavioral change.

Particular for attribute-based applications, we tend to follow the model that last-in wins which is why you see ApiResponseProvider modeling that behavior. It might be possible to change this by supporting things like the Results union type in particular (see here).

[fakhrulhilal]

I'll vote this up. Here is my sample scenario: consider this API endpoint GET [base_url]/resource?loadChildren=1, and with this DTO definitions:

[JsonDerivedType(typeof(ParentWithChildrenDto))]
public record ParentDto(int Id);
public record ParentWithChildrenDto(int Id, ChildDto[] Children) : ParentDto(Id); 
public record ChildDto(int Id, string Name);

then when loadChildren is false, then it will return ParentDto, otherwise, it will return ParentWithDto. Currently, I'm setting up the API like this, so (as you might guess), a parent with children will win. All I need to do is just adding little extra in the API description so the consumer will not get lost.

[HttpGet]
[ProduceResponseType<ParentDto>(StatusCodes.Status200OK)]
[ProduceResponseType<ParentWithChildrenDto>(StatusCodes.Status200OK)]

[spaasis]

The openapi OneOf can be utilized by inheritance (at least via Swashbuckle .UseOneOfForPolymorphism()) but that is not suitable if your endpoint would return e.g. 2 out of 3 available types:

public abstract class MyOutput{
  public sealed class MyFirstOutput : MyOutput;
  public sealed class MySecondOutput : MyOutput;
  public sealed class MyThirdOutput : MyOutput;
}

    [ProducesResponseType(typeof(MyOutput), Status200OK)] //this gives all three options
    //whereas this would be the ideal solution
    [ProducesResponseType(typeof(MyFirstOutput), Status200OK)]
    [ProducesResponseType(typeof(MyThirdOutput), Status200OK)]
    public async Task<MyOutput>> Get() => ...

[captainsafia]

We didn't get around to doing this in .NET 9 unfortunately. I'm closing this issue in favor of #56177 which tracks a similar request. Giving a thumbs up on that issue is a good way to indicate interest and help us prioritize it in the future.