Swashbuckle.aspnetcore: [5.0.0] When serializing to v2 body parameter name is not honored

[epignosisx]

While migrating from 4.0.1 to 5.0.0 and still serializing to v2:

app.UseSwagger(n => n.SerializeAsV2 = true);

I noticed that the body parameter name is no longer honoring the name of the argument in the action method:

[HttpPost("Confirmation/Email", Name = "Accessibility_SendConfirmationEmail")]
[ProducesResponseType((int)HttpStatusCode.OK)]
public async Task<IActionResult> Index([FromBody]ConfirmationEmailApiRequest apiRequest)
{
   ....
}

It is now returning "body" instead of "apiRequest":

Even, if I apply an IOperationFilter still doesn't work:

public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
    foreach(var param in operation.Parameters)
    {
        if (param.Name == "body")
            param.Name = "apiRequest";
    }
}

[kylepope-ge]

This appears to also be an issue in v5.0.0.

[epignosisx]

Didn't know v5.0.0 had come out. Upgraded and issue is still present. I have updated the bug report.

[domaindrivendev]

Hmmm - this is a bit of a tricky one. The Swagger / OpenAPI is _always_ generated in the 3.0 format and then we use a feature of the OpenAPI.NET library to convert to the V2 format at serialization time. However, in V3, body descriptions are assigned to a separate requestBody property instead of being a named parameter in the parameters collection. Therefore, the V3 document never even has a name that can be mapped back to the V2 document. So, the OpenAPI library gives it a default name of body.

I can't think of any way around this without a significant refactor and it would certainly involve some upstream changes to the OpenAPI.NET library as a pre-requisite. Given that there is only ever one body parameter, and a specific body name is never actually part of a HTTP request, does it really matter if it has the name body as opposed to whatever else you want to call it? If it's a showstopper for you, then I'm sorry to say you're somewhat snookered.

[matthawley]

We came across this too. It's hard-coded as "body" in OpenAPI.NET

https://github.com/microsoft/OpenAPI.NET/blob/578e5870d299992b9cd8414c1a1e655a56e0403c/src/Microsoft.OpenApi/Models/OpenApiOperation.cs#L249

[epignosisx]

Here is how I noticed it: I regenerated our C# client with autorest and noticed that the operation method had changed the parameter name.

This is not a big deal for us, but this is considered a breaking change (method parameter rename) since it would break consumers using named parameters. I guess you can find someone with a strict no breaking changes policy that could be affected by this.

[domaindrivendev]

A recent update to the Microsoft.OpenApi library (thx @darrelmiller👍) enables a fairly straightforward workaround for this issue. It now supports a x-bodyName extension on the requestBody metadata, which if present will be used for the parameter name when serializing to the V2 format.

To use this, you'll need to explicitly pull in version 1.2.3 of that library or above. Then, you can wire up a simple IRequestBodyFilter to set the extension value accordingly.

// Startup.cs
services.AddSwaggerGen(c =>
{
    ...
    c.RequestBodyFilter<SetBodyNameExtension>();
}

// SetBodyNameExtension.cs
public class RequestBodyExtensionsFilter : IRequestBodyFilter
{
    public void Apply(OpenApiRequestBody requestBody, RequestBodyFilterContext context)
    {
        var parameterInfo = context.BodyParameterDescription?.ParameterInfo();

        if (parameterInfo != null)
        {
            requestBody.Extensions.Add("x-bodyName", new OpenApiString(parameterInfo.Name));
        }
    }
}