如何标注返回多类型响应的控制器以生成正确Swagger文档

问题根源在于你设置的[Produces(MediaTypeNames.Application.Zip)]全局属性——它会给所有响应（包括错误状态码）默认指定application/zip的Content-Type，导致Swagger把404、416的错误响应也标记成了该类型。

要修正这个问题，只需要给错误状态码对应的[ProducesResponseType]显式指定MediaType即可，同时也可以给成功响应明确标注类型，让语义更清晰：

[HttpGet("download/{id}")]
// 成功响应指定application/zip类型
[ProducesResponseType(typeof(FileStreamResult), StatusCodes.Status200OK, MediaTypeNames.Application.Zip)]
[ProducesResponseType(typeof(FileStreamResult), StatusCodes.Status206PartialContent, MediaTypeNames.Application.Zip)]
// 错误响应指定application/json类型
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status404NotFound, MediaTypeNames.Application.Json)]
[ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status416RangeNotSatisfiable, MediaTypeNames.Application.Json)]
// 可选：如果所有响应都已显式指定MediaType，这个全局Produces可以去掉，避免默认值干扰
[Produces(MediaTypeNames.Application.Zip)]
public ActionResult Download(Guid id)
{
}

修改后，Swagger生成的swagger.json里，404和416响应就会正确显示为application/json类型的ErrorResponse，完全符合你期望的格式。

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