如何让NSwag C#客户端生成器使用现有DTO而非生成新DTO？

核心逻辑 #

NSwag支持通过类型映射配置，将OpenAPI Schema中定义的类型直接关联到你已有的DTO类型，同时关闭自动生成这些类型的逻辑，以此复用独立程序集中的DTO。

具体实现步骤 #

1. 先确保引用DTO程序集 #

无论用哪种生成方式，都要先把包含DTO的独立程序集添加为生成项目的引用，或者在生成时指定程序集的路径，让NSwag能识别到这些类型。

2. NSwagStudio可视化配置 #

• 打开NSwagStudio，加载你的OpenAPI/Swagger文档
• 切换到「CSharp Client」标签页
• 在「TypeScript/C# Settings」区域找到**「Type Mappings」**：
  • 点击「Add」，输入OpenAPI Schema里的类型名（比如UserDto），再在「CSharp Type」中填写现有DTO的完整命名空间+类型名（比如MyCompany.Dtos.Users.UserDto）
• 在「Code Generation Settings」区域：
  • 如果所有DTO都已存在，直接勾选「Do not generate types」
  • 如果只复用部分DTO，就在「Excluded Type Names」中添加这些DTO的名称
• 点击「Generate Output」，生成的客户端代码会直接引用你指定的现有DTO，不会再重新生成

3. CLI命令行配置 #

使用nswag openapi2csclient命令时，添加以下关键参数：

• --type-mappings：指定Schema类型到现有DTO的映射，格式为Schema类型名:C#完整类型名，多个映射用逗号分隔
• --no-generate-types：完全禁用类型生成（适用于所有DTO都已存在的场景）；如果只复用部分，用--excluded-type-names指定不需要生成的类型

示例命令：

nswag openapi2csclient /input:swagger.json /output:ApiClient.cs /namespace:MyCompany.ApiClients /type-mappings:UserDto:MyCompany.Dtos.Users.UserDto,OrderDto:MyCompany.Dtos.Orders.OrderDto /no-generate-types

4. 代码方式集成配置 #

如果通过代码逻辑调用NSwag生成器，可通过CSharpClientGeneratorSettings配置：

var settings = new CSharpClientGeneratorSettings
{
    Namespace = "MyCompany.ApiClients",
    // 关闭自动生成DTO类型
    GenerateDtoTypes = false,
    // 添加Schema类型到现有DTO的映射
    TypeMappings =
    {
        { "UserDto", typeof(MyCompany.Dtos.Users.UserDto) },
        { "OrderDto", typeof(MyCompany.Dtos.Orders.OrderDto) }
    }
};

var generator = new CSharpClientGenerator(document, settings);
var clientCode = generator.GenerateFile();

5. 关键注意点 #

• 确保OpenAPI Schema中的类型属性名、数据类型和你现有DTO完全匹配，否则会出现序列化/反序列化异常
• 若DTO分布在多个命名空间，只需在类型映射中填写完整的命名空间+类型名即可
• 如果需要混合使用（部分复用、部分生成），不要用--no-generate-types，而是通过--excluded-type-names指定已存在的DTO

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