Models used in Minimal API Endpoint Metadata do not respect the Swashbuckle Annotations Attributes

[syedsuhaib]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I am using the Delegate overload of MapGet / MapDelete in a custom extension method of IEndpointRouteBuilder to add a couple of endpoints - which then gets called in the main Program.cs. Currently, I am calling WithOpenApi() on the RouteGroupBuilder before calling the MapX extension methods:

 public static IEndpointRouteBuilder MapTwoEndpoints(this IEndpointRouteBuilder endpoints)
 {
     var group = endpoints.MapGroup("/base");

   group.AddEndpointFilterFactory(/* some validation related filters */)
        .WithOpenApi(op =>
        {
            op.Parameters.Add(
                  /* details omitted */
            );
            return op;
        });

     group.MapGet("/{Id}", async ([AsParameters] RequestModel request, [FromServices] ISomeService service)
         =>
     {
        /* call the service */
         return TypedResults.Ok(myResponse); // myResponse is returned from the service
     })
         .Produces<MyResponse>()
         .Produces<Error>(StatusCodes.Status404NotFound); // Error model is defined elsewhere

     group.MapDelete("/{Id}", async ([AsParameters] RequestModel request, [FromServices] ISomeService service)
         =>
     {
         /* call the service */
         return TypedResults.NoContent();
     })
         .Produces(StatusCodes.Status204NoContent);

     return group;
 }

I would like to customize the display title of the response dto (MyResponse) in Swagger. While using controllers, decorating the response model with a [SwaggerSchema(Title = "Something")] would do the trick. However, this no longer seems to be respected by minimal APIs. SwaggerUI still shows the type name under 'Schema' at the bottom, rather than the value of Title specified via the SwaggerSchemaAttribute decoration.

Please note that:

1. I am using the [AsParameters] attribute on the request model; hope that is not affecting the way endpoint metadata is constructed?
2. My response model is a record, not a plain class.

Expected Behavior

The display title of the request or response model as specified via the SwaggerSchemaAttribute on the respective models should be generated in the Open API json file and also visible in the Swagger UI.

Steps To Reproduce

[SwaggerSchema(Title = "SchemaNameToShowInSwagger", Description = "I also expect to see this description is swagger.")]
public class MyResponse
{
}

Exceptions (if any)

None

.NET Version

8.0.100

Anything else?

Already saw #44970 and #2652. Was advised to create a separate issue.

[captainsafia]

@syedsuhaib I suspect that this issue might be related to the order in which Swashbuckle's annotations are processed on endpoints relative to the WithOpenApi call. See the issue reported at domaindrivendev/Swashbuckle.AspNetCore#2561.

As an alternatively, you can consider setting the title and description yourself using the WithOpenApi method:

.WithOpenApi(operation => {
   operation.Responses["200"].Description = "..."
});

[ghost]

Hi @syedsuhaib. We have added the "Needs: Author Feedback" label to this issue, which indicates that we have an open question for you before we can take further action. This issue will be closed automatically in 7 days if we do not hear back from you by then - please feel free to re-open it if you come back to this issue after that time.

[syedsuhaib]

@captainsafia, I tried your suggestion, and it sets the description of the response itself. However, what I am after is to customize the name of the type which this response returns in body (i.e, name of the schema generated in OpenAPI JSON):

I would like the control over nomenclature of all schemas that are used by various requests and responses and are also displayed by Swagger UI at the end:

As I mentioned, currently, it defaults to the C# type name which - as per practice of many developers - may have suffix "dto" for example. Motivation to customize would be to make it friendlier to the consuming developers.

[captainsafia]

@syedsuhaib We just published an announcement about the future of OpenAPI support in the ASP.NET Core over in this issue.

One of the things that we are considering is adding first-class support for aggregating XML doc info into the generated OpenAPI document as tracked in #39927.

Since I believe that would solve your dilemma of being able to add descriptions to response types I'm going to close this issue in favor of using the other one to track this work.