Swagger 3.0(OpenAPI 3.0.3)无法返回图片响应的问题排查

修复方案 #

1. 补充控制器的Produces属性 #

控制器未明确声明响应媒体类型，导致Swagger UI默认尝试以JSON解析图片响应，引发错误。给控制器添加[Produces("image/png")]属性，明确指定返回类型：

[HttpGet("icons")]
[Produces("image/png")] // 新增此属性
[OpenApiOperation(operationId: nameof(GetLegendIcon), summary: "Get legend icon", "Proxy for icon request for legends which use one.")]
// 其他属性保留
public async Task<IActionResult> GetLegendIcon([FromQuery] GetLegendIconRequest request, CancellationToken cancellationToken)
{
    // 方法逻辑不变
}

2. 完善Swagger响应配置 #

给200响应补充二进制格式的schema定义，帮助Swagger正确识别响应类型：

responses:
  '200':
    description: 成功返回PNG格式图标
    content:
      image/png:
        schema:
          type: string
          format: binary
  '500':
    description: 服务器内部错误

3. 验证图片字节流有效性 #

确认_cachedLayerDetailsManager.GetLegendIconCachedAsync返回的是完整有效的PNG字节数据，避免因内容损坏导致解析异常。

4. 直接验证接口可用性 #

若Swagger UI仍有问题，可通过浏览器、Postman等工具直接调用接口，确认是否能正常返回图片。若工具能正常获取，说明是Swagger UI的默认解析逻辑问题，上述两步修复即可解决。

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