如何用NSwag从多版本API生成带过时标记的统一C#客户端？

当然有可行的方案！NSwag本身就支持多版本Swagger文档的合并与客户端生成，而且能完美保留旧版本接口的[Obsolete]标记，不用先手动合并Swagger JSON文件，下面给你两种实用的实现方式：

方案1：通过NSwag CLI快速实现 #

NSwag的命令行工具提供了专门的文档合并功能，能将多个Swagger JSON文件合并为一个，再基于合并后的文档生成带过时标记的C#客户端：

1. 获取各版本Swagger JSON：先从你的API服务器下载v0.1和v0.2版本的Swagger JSON文件（比如命名为swagger_v01.json和swagger_v02.json）。
2. 合并Swagger文档：执行NSwag CLI的合并命令，确保所有接口都被保留：

nswag merge /input:swagger_v01.json /input:swagger_v02.json /output:merged_swagger.json /merge:AllOf

这里的/merge:AllOf参数会避免同路径接口被覆盖，如果存在路径相同的跨版本接口，NSwag会在后续生成客户端时自动处理为重载或带版本后缀的方法。
3. 生成带过时标记的客户端：基于合并后的文档生成C#代码，关键参数确保[Obsolete]特性被生成：

nswag swagger2csclient /input:merged_swagger.json /output:ApiClient.cs /generateObsoleteAttributes:true

/generateObsoleteAttributes:true会让NSwag把Swagger规范中由[Obsolete]转换来的deprecated字段，还原为C#的[Obsolete]特性，完美保留旧接口的过时标记。

方案2：通过C#代码自定义合并与生成 #

如果需要更灵活的合并逻辑（比如处理重复Schema、自定义命名规则），可以直接用NSwag的.NET API实现：

using NSwag;
using NSwag.CodeGeneration.CSharp;
using System.IO;

// 加载两个版本的Swagger文档
var swaggerV01 = await OpenApiDocument.FromUrlAsync("http://your-api-domain/swagger/0.1/swagger.json");
var swaggerV02 = await OpenApiDocument.FromUrlAsync("http://your-api-domain/swagger/0.2/swagger.json");

// 合并文档（可根据需求扩展合并逻辑）
var mergedDoc = new OpenApiDocument();
// 合并接口路径
mergedDoc.Paths.AddRange(swaggerV01.Paths);
mergedDoc.Paths.AddRange(swaggerV02.Paths);
// 合并数据模型Schema
mergedDoc.Components.Schemas.AddRange(swaggerV01.Components.Schemas);
mergedDoc.Components.Schemas.AddRange(swaggerV02.Components.Schemas);
// 若有安全定义、响应模板等，也可按需合并

// 配置客户端生成器，启用过时标记生成
var clientSettings = new CSharpClientGeneratorSettings
{
    ClassName = "UnifiedApiClient",
    Namespace = "Your.Project.ApiClients",
    GenerateObsoleteAttributes = true, // 核心配置：保留过时标记
    // 可自定义方法命名规则、接口风格等
};

var generator = new CSharpClientGenerator(mergedDoc, clientSettings);
var clientCode = generator.GenerateFile();

// 保存生成的客户端代码
File.WriteAllText("UnifiedApiClient.cs", clientCode);

关键注意事项 #

• Swashbuckle的deprecated转换：ASP.NET Core 1.1的Swashbuckle默认会把[Obsolete]属性转换为Swagger规范中的deprecated字段，NSwag正是通过识别这个字段来生成[Obsolete]特性的，所以无需额外配置Swashbuckle。
• 重复路径处理：如果两个版本存在路径相同的接口，NSwag会自动生成重载方法或带版本后缀的方法名（比如GetUserAsync和GetUserV01Async），你也可以通过clientSettings.OperationNameGenerator自定义命名规则。
• 兼容性：NSwag对ASP.NET Core 1.1的Swashbuckle生成的Swagger文档完全兼容，不用担心版本适配问题。

这样就能直接用NSwag实现你的需求，不用再依赖AutoRest的合并功能啦。

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