NSwag生成含$type属性的无效swagger.json问题排查求助

排查方向 #

• 包版本一致性核查
  偶发问题大概率和依赖版本差异有关，重点核对以下包的版本是否和稳定环境完全一致：

  • NSwag.AspNetCore（及相关NSwag衍生包）
  • Newtonsoft.Json
    用dotnet list package命令导出本地依赖列表，和稳定环境的列表对比，重点看间接依赖的版本是否被意外升级/降级。

• 全局序列化配置检查
  检查项目Startup/Program.cs中的全局Newtonsoft.Json配置，确认是否存在根据环境动态设置TypeNameHandling的逻辑：

  services.AddControllers()
      .AddNewtonsoftJson(options =>
      {
          // 确保这里是TypeNameHandling.None，而非Auto/All
          options.SerializerSettings.TypeNameHandling = TypeNameHandling.None;
      });
  

  同时核对本地环境对应的配置文件（如appsettings.Development.json），是否有覆盖序列化配置的项。

• NSwag专属配置验证
  NSwag自身的OpenAPI文档生成配置可能独立于全局序列化设置，检查代码中AddOpenApiDocument的配置：

  services.AddOpenApiDocument(config =>
  {
      // 主动初始化SerializerSettings，避免继承全局意外配置
      if (config.SerializerSettings == null)
      {
          config.SerializerSettings = new JsonSerializerSettings();
      }
      config.SerializerSettings.TypeNameHandling = TypeNameHandling.None;
  });
  

• 运行时动态配置排查
  检查是否有代码根据特定条件（如环境变量、功能开关）动态修改序列化配置，比如在Development环境下临时开启TypeNameHandling。

解决方法 #

• 锁定依赖版本
  在Directory.Packages.props或项目csproj中明确指定NSwag和Newtonsoft.Json的版本，防止不同环境拉取不一致的依赖：

  <PackageReference Include="NSwag.AspNetCore" Version="13.20.0" />
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  

  执行dotnet restore --force强制同步依赖版本。

• 强制NSwag使用独立序列化设置
  在NSwag的文档配置中显式初始化并设置SerializerSettings，彻底隔离全局配置的影响：

  services.AddOpenApiDocument(config =>
  {
      config.SerializerSettings = new JsonSerializerSettings
      {
          TypeNameHandling = TypeNameHandling.None,
          NullValueHandling = NullValueHandling.Ignore
      };
  });
  

• 统一环境配置
  确保同事本地的ASPNETCORE_ENVIRONMENT环境变量与稳定环境一致，或移除环境差异化的序列化配置逻辑。

临时恢复手段 #

• 手动清理swagger.json
  用文本编辑器或脚本批量删除swagger.json中所有包含"$type": "..."的行，再执行NSwag生成TypeScript文件的命令。

• 临时切换依赖版本
  删除本地项目的bin/obj文件夹，还原稳定环境的依赖版本（dotnet restore --packages ./packages指定稳定包源），重新运行服务生成正确的swagger.json。

• NSwag CLI参数规避
  生成TS文件时添加/ignoreTypeNames参数，强制忽略类型名称相关的属性：

  nswag openapi2tsclient /input:swagger.json /output:Client.ts /ignoreTypeNames
  

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