我怎样才能告诉Swashbuckle人体必需的成分? [英] How can I tell Swashbuckle that the body content is required?

问题描述

我有一个WebAPI控制器，该控制器接受二进制包并将它们存储在某个位置.由于这些包可能会变得很大，因此我不想通过添加字节数组参数将它们加载到内存中，而是希望将其传递给流.

I have a WebAPI controller that accepts binary packages and stores them somewhere. As these packages can become quite large, I don't want to load them into memory by adding a byte array parameter but rather pass along a stream.

在此答案中，我找到了一种方法 :

I found a way to do that in this answer:

[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生成详尽的文档，当然，这里没有提到所需的正文内容.

This works, I can send files to the controller using Postman. However, I now want to generate swagger documentation with Swashbuckle and of course, the required body content is not mentioned there.

是否有一种方法可以获取请求的内容流，以便Swashbuckle知道?还是有一个我可以用来告知所需内容的属性?

Is there a way to get a stream of the request's content so that Swashbuckle knows about it? Or is there an attribute I can use to tell it about the required content?

推荐答案

要实现此目的，您需要做几件事.

To achieve this you have to do a couple of things.

首先，您必须告诉Swagger主体中有一个包含二进制数据的参数.接下来，您必须告诉Swagger，端点消耗了二进制数据(例如application/octet-stream).

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不支持此功能.但是您可以创建自定义过滤器来扩展Swashbuckle的功能.我通常要做的是创建一个自定义属性来装饰方法，然后创建一个自定义过滤器以对该属性进行操作.

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:

自定义属性

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用户界面中，您将得到:

In Swagger UI you then get:

这篇关于我怎样才能告诉Swashbuckle人体必需的成分?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！