How can I tell Swashbuckle that the body content is required?
To achieve this you have to do a couple of things.
First you have to tell Swagger there's a parameter in the body that contains binary data. Next you have to tell Swagger that the end point consumes binary data (e.g. application/octet-stream).
Swashbuckle does not support this out of the box. But you can create custom filters to extend the functionality of Swashbuckle. What I usually do is create a custom attribute to decorate a method and then create a custom filter to act upon that attribute.
In your case this would do the trick:
The custom attribute
public class BinaryPayloadAttribute : Attribute
{
public BinaryPayloadAttribute()
{
ParameterName = "payload";
Required = true;
MediaType = "application/octet-stream";
Format = "binary";
}
public string Format { get; set; }
public string MediaType { get; set; }
public bool Required { get; set; }
public string ParameterName { get; set; }
}
The custom filter
public class BinaryPayloadFilter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
var attribute = apiDescription.GetControllerAndActionAttributes<BinaryPayloadAttribute>().FirstOrDefault();
if (attribute == null)
{
return;
}
operation.consumes.Clear();
operation.consumes.Add(attribute.MediaType);
operation.parameters.Add(new Parameter
{
name = attribute.ParameterName,
@in = "body",
required = attribute.Required,
type = "string",
format = attribute.Format
});
}
}
Add the filter to the Swashbuckle configuration
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
// other configuration setting removed for brevity
c.OperationFilter<BinaryPayloadFilter>();
});
Apply the attribute to your method
[HttpPost]
[BinaryPayload]
[Route("Store/{projectId}")]
public async Task Store(string projectId)
{
...
}
In Swagger UI you then get:
In Swashbuckle 4.0 the syntax has changed a little:
public class BinaryPayloadAttribute : Attribute
{
public BinaryPayloadAttribute()
{
ParameterName = "payload";
Required = true;
MediaType = "application/octet-stream";
Format = "binary";
}
public string Format { get; set; }
public string MediaType { get; set; }
public bool Required { get; set; }
public string ParameterName { get; set; }
}
public class BinaryPayloadFilter : IOperationFilter
{
public void Apply(Operation operation, OperationFilterContext context)
{
var attribute = context.MethodInfo.DeclaringType.GetCustomAttributes(true)
.Union(context.MethodInfo.GetCustomAttributes(true))
.OfType<BinaryPayloadAttribute>().FirstOrDefault();
if (attribute == null)
{
return;
}
operation.Consumes.Clear();
operation.Consumes.Add(attribute.MediaType);
operation.Parameters.Add(new BodyParameter
{
Name = attribute.ParameterName,
@In = "body",
Required = attribute.Required,
Schema = new Schema
{
Type = "string",
Format = attribute.Format
}
});
}
}
And:
services.AddSwaggerGen(c =>
{
c.OperationFilter<BinaryPayloadFilter>();
});
Yet another update. Here's the solution I ended up with using ASP.NET Core 3.1
and Swashbuckle.AspNetCore.Swagger 5.0.0
:
public class BinaryContentAttribute : Attribute
{
}
public class BinaryContentFilter : IOperationFilter
{
/// <summary>
/// Configures operations decorated with the <see cref="BinaryContentAttribute" />.
/// </summary>
/// <param name="operation">The operation.</param>
/// <param name="context">The context.</param>
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
var attribute = context.MethodInfo.GetCustomAttributes(typeof(BinaryContentAttribute), false).FirstOrDefault();
if (attribute == null)
{
return;
}
operation.RequestBody = new OpenApiRequestBody() { Required = true };
operation.RequestBody.Content.Add("application/octet-stream", new OpenApiMediaType()
{
Schema = new OpenApiSchema()
{
Type = "string",
Format = "binary",
},
});
}
}
ConfigureServices
in Startup.cs
:
services.AddSwaggerGen(o =>
{
o.OperationFilter<BinaryContentFilter>();
});