我如何告诉Swashbuckle需要身体内容？

Question

我有一个WebAPI控制器,它接受二进制包并将它们存储在某个地方.由于这些包可能变得非常大,我不想通过添加字节数组参数将它们加载到内存中,而是传递给流.

我在这个答案中找到了一种方法:

[HttpPost]
[Route("Store/{projectId}")]
public async Task Store(string projectId)
{
    using (var stream = await this.Request.Content.ReadAsStreamAsync())
    {
        await this.packageManager.StorePackageAsync(projectId, stream);
    }
}

这有效,我可以使用Postman将文件发送到控制器.但是,我现在想用Swashbuckle生成一个swagger文档,当然,那里没有提到所需的正文内容.

有没有办法获得请求内容的流,以便Swashbuckle知道它？或者是否有一个属性我可以用来告诉它所需的内容？

Answer 1

要做到这一点,你必须做几件事.

首先,你必须告诉Swagger,正文中有一个包含二进制数据的参数.接下来,你必须告诉Swagger终点消耗二进制数据(例如application/octet-stream).

Swashbuckle不支持开箱即用.但是您可以创建自定义过滤器来扩展Swashbuckle的功能.我通常做的是创建一个自定义属性来装饰一个方法,然后创建一个自定义过滤器来处理该属性.

在你的情况下,这将成功:

自定义属性

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, 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
        });
    }
}

将过滤器添加到Swashbuckle配置

GlobalConfiguration.Configuration 
    .EnableSwagger(c => 
        {
            // other configuration setting removed for brevity
            c.OperationFilter<BinaryPayloadFilter>();
        });

将该属性应用于您的方法

[HttpPost]
[BinaryPayload]
[Route("Store/{projectId}")]
public async Task Store(string projectId)
{
    ...
}

在Swagger UI中,您将获得:

Answer 2

又一个更新。这是我最终使用ASP.NET Core 3.1and的解决方案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在Startup.cs：

services.AddSwaggerGen(o =>
{
    o.OperationFilter<BinaryContentFilter>();
});