如何用Swagger正确记录返回二进制文档的ASP.NET Core 6.0 Web API接口？

我正在实现一个ASP.NET Core 6.0 Web API接口，根据传入的ID返回系统中的二进制文档，文档类型可能是.pdf、.txt或.docx，具体取决于ID对应的文件。接口代码如下：

[HttpGet]
public async Task<IActionResult> GetDocument([Required] int documentId)
{
   var result = _repo.GetDocument(documentId); 
   
   if (result == null)
      return NotFound();

   return File(Convert.FromBase64String(result.Data), result.MimeType, result.FileName);
}

请问用Swagger记录这类方法的正确方式是什么？可选方向包括：

• 将响应类型标记为media type为application/octet-stream的string？
• 将响应类型标记为media type为application/octet-stream的byte[]？
• 其他方式？

我使用Swashbuckle生成Swagger定义，希望通过属性实现，而非手动编辑Swagger文件。

正确方案：用ProducesResponseType标注所有可能的媒体类型 #

因为接口返回的文档类型不固定，最准确的做法是通过ProducesResponseType属性为成功响应（200 OK）明确列出所有可能的MIME类型，让Swagger准确识别接口的响应能力。

代码示例

在接口方法上添加对应属性：

[HttpGet]
// 标注所有可能的文档类型，可添加application/octet-stream作为兜底通用类型
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(FileResult), 
                     ContentTypes = new[] { 
                         "application/pdf", 
                         "text/plain", 
                         "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
                         "application/octet-stream" 
                     })]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> GetDocument([Required] int documentId)
{
   var result = _repo.GetDocument(documentId); 
   
   if (result == null)
      return NotFound();

   return File(Convert.FromBase64String(result.Data), result.MimeType, result.FileName);
}

为什么排除前两个选项？ #

• 标记为application/octet-stream的string：接口实际返回的是原始二进制流，而非Base64编码的字符串，这种标记会让Swagger误解响应格式，导致测试时出现异常。
• 标记为application/octet-stream的byte[]：虽然byte[]对应二进制，但无法体现接口支持多种特定文档类型的特性，开发者通过Swagger无法直观知道可以获取哪些格式的文件，降低了接口文档的实用性。

额外优势 #

Swashbuckle会自动识别FileResult和指定的MIME类型，在Swagger UI中调用接口后，支持直接预览PDF、文本类文件，或直接下载对应格式的文档，无需额外配置。

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