OpenAPI documentation is incorrect when using custom TryParse() binding with Minimal APIs

[martincostello]

Describe the bug

If a type with a static TryParse() method is used as a parameter for a Minimal APIs action, the OpenAPI description does not work as would be expected.

There are two examples of this I have found for MapGet() and MapPost().

MapGet

If a parameter uses a custom type which has a TryParse() method, it will be reported as an object parameter, rather than the string that is received to be parsed.

MapPost

If a parameter uses a custom type which has a TryParse() method, it will be reported as both an object query string parameter and as the request body. If [FromBody] is used on the parameter, the extra parameter is not shown.

To Reproduce

Create an empty ASP.NET Core 6 project with a reference to Swashbuckle.AspNetCore with the below code as Program.cs.

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new() { Title = builder.Environment.ApplicationName, Version = "v1" });
});

var app = builder.Build();

// Will report a student as a query string parameter and as the request body
app.MapPost("/enroll1", (Student student) => Results.NoContent())
   .Accepts<Student>("application/json");

// Will report the student in the body only
app.MapPost("/enroll2", ([FromBody] Student student) => Results.NoContent())
   .Accepts<Student>("application/json");

// Will report the parameter as an object instead of as a string
app.MapGet("/student/{student}", (Student student) => $"Hi {student.Name}");

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    options.EnableTryItOutByDefault();
    options.SwaggerEndpoint("/swagger/v1/swagger.json", $"{builder.Environment.ApplicationName} v1");
});

app.Run();

public record Student(string Name)
{
    public static bool TryParse(string value, out Student? result)
    {
        if (value is null)
        {
            result = null;
            return false;
        }

        result = new Student(value);
        return true;
    }
}

Further technical details

.NET SDK version 6.0.100-rc.1.21460.8

[BrennanConroy]

If a parameter uses a custom type which has a TryParse() method, it will be reported as an object parameter, rather than the string that is received to be parsed.

Should it always be string or should we show string for object types and int etc. for non-object types?

If a parameter uses a custom type which has a TryParse() method, it will be reported as both an object query string parameter and as the request body

This is by design, you're using a query string in your lambda and then claiming there is also a body by using Accepts.

[martincostello]

Should it always be string or should we show string for object types and int etc. for non-object types?

Good point, that makes more sense.

This is by design, you're using a query string in your lambda and then claiming there is also a body by using Accepts.

Maybe I've misunderstood - because it's an object on a POST action, I thought it would automatically bind it to the body by default if it was an object?

[BrennanConroy]

because it's an object on a POST action, I thought it would automatically bind it to the body by default if it was an object?

Normally, but you have a TryParse on the object so we treat it as query or route

[martincostello]

@davidfowl Maybe worth adding the above to your Minimal APIs gist documentation?

[davidfowl]

It's there in fine print: https://gist.github.com/davidfowl/ff1addd02d239d2d26f4648a06158727#custom-binding

For route, query, and header binding sources, you may bind custom types by adding a static TryParse method to your type.