Swashbuckle.AspNet.Core：Swagger UI 显示空白页面 - 如何修复？

Posted 2023-03-31

【中文标题】Swashbuckle.AspNet.Core：Swagger UI 显示空白页面 - 如何修复？

【英文标题】：Swashbuckle.AspNet.Core: Swagger UI shows empty page - How to fix?

【发布时间】：2020-07-19 17:04:14

【问题描述】：

我将 Swashbuckle.AspNet.Core 添加到我的存储库并使用默认值初始化所有内容。

虽然我可以看到来自 /swagger/v1/swagger.json 的 JSON 输出打开 /swagger/index.html 只是产生一个空页面。

为什么？

---

这是我的代码

public void ConfigureServices(IServiceCollection services)

  services
    .AddSwaggerGen()
    .AddControllers()
    ;


// This method gets called by the runtime once. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env, Options options)

  if (env.IsDevelopment()) app.UseDeveloperExceptionPage();

  app
    .UseHttpsRedirection()
    .UseRouting()
    .UseAuthorization()
    .UseEndpoints(endpoints => endpoints.MapControllers())
    .UseSwagger()
    ;

  if (env.IsDevelopment()) app.UseSwaggerUI();

【问题讨论】：

尝试根目录，即 / 或 /swagger 或 /swagger/index.html。使用 c.RoutePrefix = string.Empty; 会导致 UI 页面在 root 上呈现。

【参考方案1】：

您没有正确配置 Swashbuckle 服务。

在您的 configureServices 方法中，对 AddSwaggerGen 的调用具有“可选参数”，因此您指定的方式将起作用，但更常见的是执行以下操作：

  services.AddSwaggerGen(config =>
  
    config.SwaggerDoc("v1", new OpenApiInfo()  Title = "Payment Card Info API", Version = "v1" );
  );

Title 是您的 Swagger Doc 将显示的标题，version 是在您的文档上显示的 API 的广告版本，第一个“v1”参数是用于实际 Swagger URL 的版本参数服务器 json 文件。

但是，您在“配置”方法中放置的代码不是可选的，必须以特定方式完成。

app.UseSwagger();
app.UseSwaggerUI(config =>

  config.SwaggerEndpoint("/swagger/v1/swagger.json", "Payment Card Info API");
);

“UseSwaggerUI 调用必须手动配置，因为看起来代码中的默认设置根本无法自动工作。

默认情况下，您的 swagger json 文档将始终位于 "/swagger/" + swaggerDoc 调用中的第一个版本参数 + "/swagger.json"（这个可以改，但不推荐）

您的 swagger 端点调用，必须是提供 json 的实际 URL，以及您选择的名称来标记它。

我还强烈建议将您的 UseSwaggerUI 调用包装在“env.IsDevelopment”调用中，以便在您对应用进行生产构建时自动关闭它，因此在部署您的服务后不会使其可用。

这就是我的做法。