使用SwashBuckle返回文件流遇编码异常，求正确实现方案

这个问题的核心是Swashbuckle默认把接口标记为返回JSON/XML文本，导致二进制文件流被错误执行UTF-8编码，最终出现文件体积变大、内容异常的情况。咱们一步步来解决：

1. 明确指定接口的输出MIME类型 #

给控制器Action添加[Produces("application/octet-stream")]特性，覆盖Swagger默认的JSON/XML输出类型，明确告知这是二进制流接口：

[System.Web.Http.HttpGet]
[System.Web.Http.Route("Files/{uid}/file")]
[Produces("application/octet-stream")] // 关键：指定二进制流的MIME类型
[SwaggerResponse(HttpStatusCode.OK, Description = "文件流", ContentTypes = new[] { "application/octet-stream" })]
public HttpResponseMessage DownloadFile(String uid, String fileName)
{
    return Safe.Execute(() =>
    {
        var api = new FileApi();
        var stream = api.GetFile(uid, fileName);
        
        HttpResponseMessage result = new HttpResponseMessage(HttpStatusCode.OK);
        result.Content = new StreamContent(stream);
        result.Content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
        
        // 对文件名做URL编码，避免中文、特殊字符导致的下载异常
        var encodedFileName = HttpUtility.UrlEncode(CalcFileName(fileName));
        result.Content.Headers.ContentDisposition = new ContentDispositionHeaderValue("attachment")
        {
            FileName = encodedFileName,
            FileNameStar = encodedFileName // 兼容RFC 5987标准，适配更多浏览器
        };
        
        return result;
    });
}

2. 调整SwaggerResponse特性配置 #

不需要再指定Type = typeof(Byte[])或typeof(Stream)，而是通过ContentTypes明确告诉Swagger响应的内容类型是二进制流。修改后生成的Swagger文档中，produces会替换为["application/octet-stream"]，彻底摆脱默认的JSON/XML类型。

3. 验证Swagger文档生成结果 #

修改完成后，你的Swagger接口描述应该变成类似这样：

"produces": [
  "application/octet-stream"
],
...
"responses": {
  "200": {
    "description": "文件流",
    "content": {
      "application/octet-stream": {
        "schema": {
          "type": "string",
          "format": "binary"
        }
      }
    }
  }
}

这里的format: binary是核心，它会让Swagger UI把响应当作二进制文件处理，而非文本字符串，从根源避免UTF-8编码转换导致的文件损坏。

为什么之前的配置无效？ #

你之前的代码里，Swagger默认的produces是JSON/XML，即便设置了SwaggerResponse的Type为Byte[]或Stream，Swagger UI依然会按文本类型处理响应，把二进制流转换成UTF-8字符串，最终插入额外字节、增大文件体积。通过添加[Produces]特性强制指定输出类型，就能彻底解决这个编码问题。

内容的提问来源于stack exchange，提问作者Zoltan Hernyak