ASP.NET Blazor项目自定义Shared类与Swagger生成类冲突最佳解决方案

1. 解决类重复定义冲突 #

Swagger存根代码生成工具（常见为NSwag、OpenAPI Generator）均支持配置排除已有类型，无需修改生成后的代码，配置永久生效：

• 若使用dotnet openapi命令生成代码：
  执行生成命令时添加--exclude-type参数指定你Shared项目下的模型命名空间，示例：
  dotnet openapi add url https://your-api/swagger/v1/swagger.json --exclude-type YourProject.Shared.Models.*
  也可以直接编辑Blazor项目的.csproj文件，修改OpenApiReference节点：

  <OpenApiReference Include="swagger.json" SourceUrl="https://your-api/swagger/v1/swagger.json">
    <ExcludedTypes>YourProject.Shared.Models.*</ExcludedTypes>
    <Namespace>YourProject.Blazor.ApiClients</Namespace>
  </OpenApiReference>
  

  配置后生成工具不会再自动生成Shared项目已存在的Contract类，生成的Service.cs会直接引用Shared项目的类型，无需强制类型转换。
• 若使用NSwagStudio等可视化工具生成：
  在生成配置的「类型排除」项中添加Shared项目的模型命名空间，同时将生成代码的命名空间设置为独立的ApiClients类命名空间，避免和现有代码命名冲突。
• 禁止直接修改自动生成的Contract.cs/Service.cs，自定义逻辑可通过partial部分类扩展，下次生成不会覆盖自定义代码。

2. 解决重复DbContext问题 #

自动生成多余DbContext的核心原因是API项目的Swagger文档将内部DbContext类型暴露到了OpenAPI Schema中，两步解决：

• 第一步：修改API项目的Swagger配置，排除DbContext类型不对外暴露：

  builder.Services.AddSwaggerGen(options =>
  {
      // 过滤所有继承自DbContext的类型
      options.TypeFilter<OmitDbContextFilter>();
  });
  // 过滤器实现示例
  public class OmitDbContextFilter : ISchemaFilter
  {
      public void Apply(OpenApiSchema schema, SchemaFilterContext context)
      {
          if (typeof(DbContext).IsAssignableFrom(context.Type))
          {
              schema.Items = null;
              schema.Properties.Clear();
          }
      }
  }
  

• 第二步：在存根代码生成配置中，将DbContext类型也加入排除列表，重新生成后自动删除多余的DbContext类。
• 可选优化：在你自定义DbContext所在的项目.csproj中添加默认上下文配置，后续EF Core命令无需每次加--context参数：

  <PropertyGroup>
    <DefaultDbContext>YourProject.Shared.Data.YourCustomDbContext</DefaultDbContext>
  </PropertyGroup>
  

最佳实践总结 #

• 所有跨项目共用的模型类统一放到Shared项目维护，作为全解决方案的唯一模型源，避免多处定义
• API项目Swagger仅暴露对外接口相关的模型，过滤内部依赖类型（DbContext、内部服务类等）
• 使用MSBuild集成Swagger存根生成逻辑，将生成配置固化到项目文件中，编译时自动更新API客户端代码，避免手动下载修改生成文件
• 生成的API客户端类使用独立命名空间管理，和业务代码、Shared模型代码隔离

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