OpenAPI代理工具流IO处理及NSWag代理类型映射问题咨询

问题涉及接口代码 #

[HttpGet]
public ActionResult<Stream> ReadStreamFromFile(string fileNameWithFullPath)
{
    byte[] byteArray = System.IO.File.ReadAllBytes(fileNameWithFullPath);                    
    System.IO.MemoryStream memoryStream = new MemoryStream(byteArray);
    return memoryStream;
}

问题现象 #

使用NSWag搭配支持Microsoft CodeDOM的DLL创建服务代理时，Stream类型被生成为自定义复杂类型类，而非预期的System.IO.Stream类型，最终导致服务调用过程抛出运行时异常。

解决方法 #

• 配置NSWag类型映射规则
  在NSWag客户端生成配置（NSWag Studio可视化配置、项目内nswag.json配置文件、命令行生成参数均可）中找到类型映射配置节点，添加Stream类型的显式映射规则，将OpenAPI规范中binary/stream格式的类型直接映射为System.IO.Stream，跳过复杂类型自动生成逻辑。使用命令行生成时可直接追加参数/typeMappers:Stream=System.IO.Stream完成配置。
• 给接口添加明确的流响应标注
  原接口未声明响应内容类型，NSwag无法自动识别返回值为文件流。修改接口代码，添加[Produces("application/octet-stream")]特性，同时将返回值改为框架内置的文件流结果类型，修改后示例：

  [HttpGet]
  [Produces("application/octet-stream")]
  public IActionResult ReadStreamFromFile(string fileNameWithFullPath)
  {
      byte[] byteArray = System.IO.File.ReadAllBytes(fileNameWithFullPath);                    
      var memoryStream = new MemoryStream(byteArray);
      return File(memoryStream, "application/octet-stream");
  }
  

  修改完成后重新生成Swagger文档，NSwag可自动识别该接口返回为流类型，不会生成对应自定义复杂类。
• 生成代理时排除自动生成的Stream复杂类型
  在代理生成配置的excludeTypes节点中，添加自动生成的Stream复杂类型的完整命名空间名称，强制生成器使用全局类型解析规则匹配系统内置的System.IO.Stream类型。

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