dotnet / dotnet/aspnetcore

Using `TypedResults` and an API convention in the same project causes conflicts

Open
#67,723 2 comments 1 reaction 0 assignees View on GitHub
area-mvc feature-openapi investigate
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 10h
Merged PRs (30d)
281

Description

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Describe the bug

If you have a project that contains both
(a) API controllers using `TypedResults` and
(b) an API convention (for `IActionResult` return types which have not yet been migrated to `TypedResults`)
then the generated OpenAPI document is missing the result models of successful results (status 2xx).

Additionally, the `ProblemDetails` error results are modified to not contain the "application/problem+json" content type any more.

### Expected Behavior

The OpenAPI document should contain a result model. The red lines below show the lines that are missing because of this bug. The green lines show additions that are not expected, but not really a problem.

```diff
"paths": {
"/Test": {
"get": {
"tags": [
"Test"
],
"responses": {
"200": {
"description": "OK",
- "content": {
- "application/json": {
- "schema": {
- "type": "string"
- }
- }
- }
},
"400": {
"description": "Bad Request",
"content": {
- "application/problem+json": {
+ "text/plain": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
},
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HttpValidationProblemDetails"
+ }
+ },
+ "text/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HttpValidationProblemDetails"
+ }
}
}
}
}
}
}
},
```

### Steps To Reproduce

1. Create a new ASP.NET Core Web API project with "Use controllers" enabled.
2. Add a file with this content:
```cs
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using WebApi.Controllers;

// Apply the conventions to all controllers in this assembly.
[assembly: ApiConventionType(typeof(ApiConventions))]

namespace WebApi.Controllers;

[ApiController]
[Route("[controller]")]
public class TestController : ControllerBase
{
[HttpGet]
public Results, ValidationProblem> Get()
{
return TypedResults.Ok("Test");
}
}

public static class ApiConventions
{
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesDefaultResponseType]
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
public static void Get()
{ }
}
```
3. Start the project and request /openapi/v1.json

### Exceptions (if any)

_No response_

### .NET Version

10.0.301

### Anything else?

ASP.NET Core version: 10.0.9

Related: #64858

One additional change in the OpenAPI document that I didn't mention above is the inclusion of the default error response from `ProducesDefaultResponseType`. But this is good in my opinion. Because I don't know of a way to apply the default error response without a convention (other than adding the attribute to all controller methods).

And there are additional cases where an API convention would still be useful, even if this bug is fixed:
- Framework generated error responses: #58719
- Including `ProblemHttpResult` in the OpenAPI document: #52424

Therefore API conventions should still apply to API controllers using `TypedResults`. They just shouldn't remove information that was already there.

Contributor guide

Open the contributing guide

Research direction

Reproduce the controller and ApiConventionType setup from the issue, then request /openapi/v1.json and compare the generated responses with the expected diff. Trace the OpenAPI generation path for TypedResults combined with API conventions; done means successful result models remain present and ProblemDetails retains application/problem+json without removing convention-provided responses.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, openapi
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.