Add swagger parameters for unbound parameters in ASP.NET Core

Question

I have an ASP.NET Core 2.2 WebApi and want to upload large files with some additional metadata. The request is a multipart/form-data. Because the files to upload can get quite large, I do not want to read it into memory for processing but rather stream it directly to it's desired destination. I followed the documentation to disable form value model binding and I also adjusted the maximum request size for the endpoint.

I have tested the endpoint with postman and it works as expected:

However, Swagger obviously does not recognize that there should be parameters for the request. How can I add these parameters to the swagger documentation without defining the parameters in the method's signature?

My endpoint looks like the following example:

[HttpPost]
[DisableFormValueModelBinding]
[DisableRequestSizeLimit]
public async Task<IActionResult> Upload() // "department" and "file" needed in the multipart/form-data
{
  // var path = await uploader.UploadAsync(Request);
  // return Ok(path);
}

Usually, I would bind the parameters like the following example:

public async Task<IActionResult> Upload([FromForm] string department, [FromForm] IFormFile file)

This works as expected in Swagger but as mentioned above, I do not want to bind the parameters.

Thomas D. · Accepted Answer · 2021-02-22 17:15:28Z

For Swashbuckle.AspNetCore version 5 and above some things have changed.

To provide the parameters like Alexander did in his answer, the code would look something like the following:

operation.Parameters.Add(new OpenApiParameter()
{
    Name = "department",
    Schema = new OpenApiSchema { Type = "string", Format = "string" },
    Required = true,
});

operation.Parameters.Add(new OpenApiParameter()
{
    Name = "file",
    Schema = new OpenApiSchema { Type = "string", Format = "binary" },
    Required = true,
});

For some reason however (which I did not investigate further), I was not able to perform an call in the Swagger UI with this approach.

In the end, the following example provided me the result I was looking for:

public class AddUnboundParametersOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var descriptor = context.ApiDescription.ActionDescriptor as ControllerActionDescriptor;
    
        if (descriptor != null && descriptor.ControllerTypeInfo == typeof(RemoteUpdateController) && descriptor.ActionName == nameof(RemoteUpdateController.Upload))
        {
            var openApiMediaType = new OpenApiMediaType
            {
                Schema = new OpenApiSchema
                {
                    Type = "object",
                    Required = new HashSet<string> { "department", "file" }, // make the parameter(s) required if needed
                    Properties = new Dictionary<string, OpenApiSchema>
                    {
                        { "department" , new OpenApiSchema() { Type = "string", Format = "string" } },
                        { "file" , new OpenApiSchema() { Type = "string", Format = "binary" } },
                    }
                }
            };

            operation.RequestBody = new OpenApiRequestBody
            {
                Content = new Dictionary<string, OpenApiMediaType>
                {
                    { "multipart/form-data", openApiMediaType }
                }
            };
        }
    }
}

Oleksandr · Accepted Answer · 2021-02-20 01:42:49Z

1

You can use IOperationFilter for this. Add the following class, adjust controller and action names

public class AddUnboundParametersOperationFilter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
            operation.Parameters = new List<IParameter>();

        var descriptor = context.ApiDescription.ActionDescriptor as ControllerActionDescriptor;

        if (descriptor != null && descriptor.ControllerTypeInfo == typeof(TestController) && descriptor.ActionName == nameof(TestController.Upload))
        {
            operation.Parameters.Add(new NonBodyParameter()
            {
                Name = "department",
                Type = "string",
                Required = true,
                In = "formData",
            });

            operation.Parameters.Add(new NonBodyParameter()
            {
                Type = "file",
                In = "formData",
                Name = "file",
                Required = true
            });
        }
    }
}

In Startup.cs

services.AddSwaggerGen(c =>
{
    c.OperationFilter<AddUnboundParametersOperationFilter>();
    //...
});

answered Feb 20, 2021 at 1:42

Oleksandr

9,7601 gold badge22 silver badges45 bronze badges

1 Comment

Thomas D. Over a year ago

This definitely put me on the right track, however, your solution does not work for Swashbuckle version 5 and above. Anyways, I think this will work in earlier versions. If anyone looking for an example for version 5 and above, take a look at my answer to this question.

Collectives™ on Stack Overflow

Add swagger parameters for unbound parameters in ASP.NET Core

2 Answers 2

Comments

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related