NSwag多客户端场景下异常类生成问题的分析与解决

问题背景

在使用NSwag工具生成C#客户端代码时，当项目中包含多个OpenAPI规范文件引用（即多个<OpenApiReference>元素）时，会出现一个关键问题：ApiException类仅会为第一个引用的规范文件生成。虽然这在大多数情况下是一个合理的默认行为，但从NSwag v14版本开始，开发者无法再为后续引用的规范文件生成异常类，即使这些类位于不同的命名空间中。

问题现象

在包含多个OpenAPI引用的项目中，当尝试构建生成的客户端代码时，第二个及后续客户端会因缺少ApiException类而编译失败。这是因为生成的客户端代码会引用ApiException类，但该类并未被生成。

根本原因分析

问题的根源在于NSwag的MSBuild目标文件(NSwag.ApiDescription.Client.targets)中的逻辑缺陷。当前实现中，对于非第一个引用条目，系统会无条件地添加/GenerateExceptionClasses:false参数，完全忽略了在<OpenApiReference>中配置的NSwagGenerateExceptionClasses属性值。

技术细节

1. 当前错误实现：

<Command Condition="!%(FirstForGenerator) OR (%(NSwagGenerateExceptionClasses) != '' AND !%(NSwagGenerateExceptionClasses))">
    %(Command) /GenerateExceptionClasses:false
</Command>

2. 问题点：

• 对于非第一个引用(!%(FirstForGenerator))，无论NSwagGenerateExceptionClasses如何设置，都会强制添加/GenerateExceptionClasses:false
• 即使显式设置<Options>/GenerateExceptionClasses:true</Options>，也会因参数重复而失败

解决方案

正确的实现应该：

1. 仅对未配置NSwagGenerateExceptionClasses的非第一个引用添加/generateExceptionClasses:false
2. 对于显式配置了NSwagGenerateExceptionClasses的引用，应尊重其设置值

修正后的代码应为：

<Command Condition="!%(FirstForGenerator) AND ('%(NSwagGenerateExceptionClasses)' == '')">
    %(Command) /generateExceptionClasses:false
</Command>
<Command Condition="'%(NSwagGenerateExceptionClasses)' != ''">
    %(Command) /generateExceptionClasses:%(NSwagGenerateExceptionClasses)
</Command>

扩展问题

同样的逻辑缺陷也存在于以下相关功能中：

1. NSwagGenerateResponseClasses参数
2. 继承相关的JSON转换器类生成（JsonInheritanceConverter、JsonInheritanceConverterAttribute和JsonInheritanceAttribute），尽管这些目前没有对应的NSwag*配置属性

开发者应对策略

在官方修复发布前，开发者可以采取以下临时解决方案：

1. 将所有需要异常类的客户端合并到同一个OpenAPI规范文件中
2. 手动添加缺失的异常类到项目中
3. 修改本地NSwag安装中的目标文件，应用上述修复

总结

这个问题展示了在代码生成工具中处理多配置项时的复杂性。正确的做法应该是确保每个配置项都能被独立控制，而不是通过隐式的条件逻辑覆盖用户的显式配置。对于使用NSwag生成多客户端代码的开发者来说，理解这一机制有助于更好地规划项目结构和处理类似问题。