OpenAPI parameter descriptions are written to the wrong location

[martincostello]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

When a [Description] attribute is applied to a parameter of a Mimimal API endpoint intended to be documented with the OpenAPI functionality, the description string is written to the wrong place in the schema, which then means it is not documented by tools such as Swagger UI.

To illustrate, the JSON snippet below shows where the description should be (green) and where it currently appears (red):

{
  "name": "uppercase",
  "in": "query",
+ "description": "Whether to return the GUID in uppercase.",
  "schema": {
    "type": "boolean",
-   "description": "Whether to return the GUID in uppercase.",
    "nullable": true
  }
}

Expected Behavior

The description is added to the top-level object for the parameter definition.

Steps To Reproduce

Generate an OpenAPI document with MapOpenApi() for an endpoint similar to the below:

app.MapGet("/name", Api.GetName);

public static class Api
{
    public static Ok<string> GetName([Description("Your name")] string name)
    {
        return TypedResults.Ok($"Hi {name}!");
    }
}

Exceptions (if any)

No response

.NET Version

9.0.100-preview.4.24267.66

Anything else?

No response

[captainsafia]

@martincostello Thanks for filling this issue!

The behavior around mapping DescriptionAttribute to schema.description is handling by the underlying System.Text.Json schema mapper. As part of these APIs moving to production, this default behavior will be removed so we'll have to do the mapping at the OpenAPI-level. We can resolve the issue there.

Gonna bucket this into 9.0 for now. We'll need to do this after STJ's APIs are shipped in the library and we replat on top of them.