使用NSwag从Azure DevOps OpenAPI生成C#客户端的反序列化问题解决

一、OpenAPI文档与实际返回不一致的原因 #

Azure DevOps REST API的列表类接口普遍采用带value属性的包装对象作为返回格式，目的是统一支持分页、附加元数据（如总数、关联链接）等场景。你使用的7.2版Git模块OpenAPI文档存在疏漏，没有同步实际API的返回格式，错误地将包装对象内部的GitRepository数组直接声明为接口返回类型。

二、NSwag适配方案（按推荐度排序） #

方案1：修正OpenAPI规范文档（最优解） #

直接编辑git.json中GetRepositories接口的响应定义，把原返回的GitRepository[]替换为包含value属性的包装对象：

{
  "type": "object",
  "properties": {
    "value": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/GitRepository"
      }
    }
  }
}

重新用NSwag生成客户端后，代码会自动生成对应的包装类，你可以通过包装类的.Value属性获取仓库数组，完全匹配实际API返回格式。

方案2：配置NSwag使用自定义Json转换器 #

通过自定义JsonConverter让反序列化逻辑自动提取value属性内容：

1. 编写通用转换器类：

public class ValueWrapperConverter<T> : JsonConverter<ICollection<T>>
{
    public override ICollection<T> ReadJson(JsonReader reader, Type objectType, ICollection<T> existingValue, bool hasExistingValue, JsonSerializer serializer)
    {
        var wrapperObj = serializer.Deserialize<JObject>(reader);
        return wrapperObj["value"]?.ToObject<ICollection<T>>(serializer) ?? new List<T>();
    }

    public override void WriteJson(JsonWriter writer, ICollection<T> value, JsonSerializer serializer)
    {
        serializer.Serialize(writer, new { value = value });
    }
}

2. 在NSwag配置中添加该转换器：
   • 若用NSwag CLI，修改nswag.json：

     "jsonSerializerSettings": {
       "converters": [
         {
           "type": "你的命名空间.ValueWrapperConverter`1, 你的程序集名称"
         }
       ]
     }
     

   • 若用代码生成，配置SwaggerToCSharpClientGeneratorSettings：

     var settings = new SwaggerToCSharpClientGeneratorSettings();
     settings.JsonSerializerSettings.Converters.Add(new ValueWrapperConverter<GitRepository>());
     

生成的客户端会自动处理带value的响应，直接返回ICollection<GitRepository>类型的结果。

方案3：手动修改生成的客户端代码（临时应急） #

找到NSwag生成的GetRepositories方法，替换反序列化逻辑：

// 替换原反序列化代码
var responseWrapper = Newtonsoft.Json.JsonConvert.DeserializeObject<RepositoryResponseWrapper>(responseText, JsonSerializerSettings);
return responseWrapper.Value;

// 新增包装类
public class RepositoryResponseWrapper
{
    [JsonProperty("value")]
    public ICollection<GitRepository> Value { get; set; }
}

注意：此方法每次重新生成客户端代码都会被覆盖，仅适合临时测试场景。

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