ASP.NET Core项目发布后Swagger的index.html页面空白该如何解决？

核心原因定位 #

你遇到的发布后Swagger UI空白问题，最常见的原因是Swagger接口定义文件（swagger.json）加载失败，可以先手动访问对应路径验证：

• 本地直接运行发布版exe时访问 http://localhost:5000/swagger/v1/swagger.json
• IIS部署时访问 http://localhost:35701/swagger/v1/swagger.json
  如果返回500错误，说明后端生成swagger.json时抛出异常，优先排查XML注释文件的问题。

具体修复步骤 #

1. 配置发布时自动输出XML注释文件 #

你代码中用了IncludeXmlComments加载XML注释，默认发布时不会自动生成该文件，需要手动开启：

• 右键项目 → 选择「属性」→ 切换到「生成」标签页
• 下滑到「输出」区域，勾选「XML文档文件」，.NET Core会自动填充路径，格式为bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml
• 在同一页面的「禁止显示警告」输入框中添加1591，避免未给所有成员加注释导致的编译警告
• 保存后重新发布项目，确认发布目录下存在XoikosOnlineOrderingAPI.xml文件

2. 修正Swagger端点路径配置 #

当前你用的绝对路径/swagger/v1/swagger.json在IIS子应用部署场景下会找不到路径，改成相对路径适配性更强，修改Startup.cs中UseSwaggerUI的配置：

app.UseSwaggerUI(c => c.SwaggerEndpoint("v1/swagger.json", "XoikosOnlineOrderingAPI v1"));

3. 确认生产环境.NET运行时安装正确 #

IIS部署时必须安装对应版本的托管捆绑包，安装完成后重启IIS服务即可生效。

4. （可选）保留生产环境Swagger访问 #

如果你需要生产环境也能访问Swagger，确保UseSwagger和UseSwaggerUI没有放在if (env.IsDevelopment())代码块内，你的当前配置已经符合要求，不需要调整。

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