.NET 6中两个Swagger JSON文件内容不一致及配置问题

1. 确保两个swagger.json内容一致 #

问题源于两个端点对应的Swagger文档配置不统一，按以下步骤调整：

• 检查Program.cs中AddSwaggerGen的配置，统一API版本标识，只保留一套匹配的SwaggerDoc定义：

  builder.Services.AddSwaggerGen(c =>
  {
      c.SwaggerDoc("v1.0", new OpenApiInfo { Title = "你的API标题", Version = "v1.0" });
      // 移除多余的SwaggerDoc定义（比如针对v1的重复配置）
  });
  

• 配置Swagger端点时，让两个路径指向同一个文档：

  app.UseSwagger(c =>
  {
      c.RouteTemplate = "api-docs/{documentName}/swagger.json";
  });
  app.UseSwaggerUI(c =>
  {
      c.SwaggerEndpoint("/api-docs/v1.0/swagger.json", "API v1.0");
      c.SwaggerEndpoint("/api/swagger/v1/swagger.json", "API v1");
  });
  

• 确认所有API控制器都正确标记[ApiVersion("1.0")]，保证Swagger能扫描到完整的接口信息。

2. 使用物理位置的单个swagger.json满足两个端点需求 #

可以实现，步骤如下：

1. 导出正确的swagger.json：访问正常的api-docs/v1.0/swagger.json，将内容保存到bin/Debug/net6.0/swagger.json（或对应发布目录）。
2. 配置静态文件服务，允许访问bin目录：

   var binPath = Path.Combine(AppContext.BaseDirectory);
   app.UseStaticFiles(new StaticFileOptions
   {
       FileProvider = new PhysicalFileProvider(binPath),
       RequestPath = "/swagger-static"
   });
   

3. 修改Swagger端点配置，让两个路径都指向这个静态文件：

   app.UseSwagger(c =>
   {
       // 禁用自动生成，改用静态文件
       c.PreSerializeFilters.Add((doc, req) => throw new NotImplementedException());
   });
   app.UseSwaggerUI(c =>
   {
       c.SwaggerEndpoint("/swagger-static/swagger.json", "API v1.0");
       c.SwaggerEndpoint("/swagger-static/swagger.json", "API v1");
   });
   

   若无需动态生成文档，可直接移除AddSwaggerGen配置，仅保留静态文件和SwaggerUI的配置。

3. 编程添加paths和components节点 #

SwaggerDoc仅负责配置元信息（info），手动添加paths和components需使用DocumentFilter：

1. 创建自定义文档过滤器：

   public class CustomSwaggerDocumentFilter : IDocumentFilter
   {
       public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
       {
           // 添加自定义路径
           swaggerDoc.Paths.Add("/custom/endpoint", new OpenApiPathItem
           {
               Get = new OpenApiOperation
               {
                   Summary = "自定义GET接口",
                   Responses = new OpenApiResponses
                   {
                       ["200"] = new OpenApiResponse { Description = "成功返回" }
                   }
               }
           });
   
           // 添加自定义组件（示例为Schema）
           swaggerDoc.Components.Schemas.Add("CustomModel", new OpenApiSchema
           {
               Type = "object",
               Properties = new Dictionary<string, OpenApiSchema>
               {
                   ["Id"] = new OpenApiSchema { Type = "integer", Format = "int32" },
                   ["Name"] = new OpenApiSchema { Type = "string" }
               }
           });
       }
   }
   

2. 在AddSwaggerGen中注册过滤器：

   builder.Services.AddSwaggerGen(c =>
   {
       c.SwaggerDoc("v1.0", new OpenApiInfo { Title = "你的API标题", Version = "v1.0" });
       c.DocumentFilter<CustomSwaggerDocumentFilter>();
   });
   

   生成的swagger.json会同时包含手动添加的节点和自动扫描的API接口信息。

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