我有一个基于ASP.NET Core 9的 Web API，包含使用 IFormFile 的文件上传端点。启动应用后，Swagger UI加载失败，出现以下错误：

Failed to load API definition.
Fetch error
Internal Server Error http://localhost:5150/swagger/v1/swagger.json

此外，当我尝试附加一个文件并通过Swagger UI发送请求时，调试会话悄无声息地结束——没有异常，没有输出，调试器只是分离。

环境：

• .NET 9（net9.0）
• Swashbuckle.AspNetCore — 尝试了 10.1.4 和 6.9.0
• Microsoft.NET.Test.Sdk 17.12.0
• Visual Studio 2022

代码 - 控制器：

[ApiController]
[Route("api/[controller]")]
public class ConverterController : ControllerBase
{
    [HttpPost("convert-to-sbv")]
    [Consumes("multipart/form-data")]
    public IActionResult ConvertToSbv([FromForm] IFormFile file)
    {
        if (file == null || file.Length == 0)
            return BadRequest("File wasn't selected.");

        return Ok("File was accepted, but conversion wasn't done.");
    }
}

Program.cs：

using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.MapControllers();
app.MapGet("/", () => Results.Redirect("/swagger/index.html"));

app.Run();

.csproj 项目文件：

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.9.0" />
  </ItemGroup>
</Project>

我尝试了以下方法：

1. 增加 [FromForm] 属性
没有它，IFormFile 无法正确绑定。明确添加后——仍未解决swagger.json的 500。

2. 移除了 async Task<IActionResult>，因为没有 await
改为普通的 IActionResult — 对Swagger问题没有影响。

3. 使用文件存在性检查来保护 IncludeXmlComments

if (File.Exists(xmlPath))
    c.IncludeXmlComments(xmlPath);

构建输出中确实存在该XML文件。仍然500。

4. 将Swashbuckle从 10.1.4降级到6.9.0
Swashbuckle 10.x引入对 Microsoft.OpenApi v2.0的依赖，其中存在破坏性API变更——Microsoft.OpenApi.Models 命名空间解析不正确，导致 MapType<IFormFile>() 的变通方法不可用。降级到6.9.0 —— 仍然500。

5. 移除了 AddEndpointsApiExplorer()
这是为最小化API（minimal APIs）设计的；对于基于控制器的API来说它是冗余的，可能会引发重复的API描述问题。移除后——仍然500。

问题

是什么原因导致 swagger.json 生成在一个简单的 IFormFile 上传端点上，在ASP.NET Core 9与 Swashbuckle 6.9.0的环境中返回500 Internal Server Error？以及如何修复？

更新 / 解决方案

起初我以为这个问题与Swagger有关，因为在请求 /swagger/v1/swagger.json 时就出现错误。不过，我后来发现问题并不限于Swagger。

即使我创建一个简单的静态HTML页面，使用JavaScript直接调用控制器端点，我仍然收到应用静默关闭，没有任何可见的异常或响应。即使增加了额外的异常处理程序，也没有捕获异常，这让调试非常困惑。

最终我尝试彻底卸载 Visual Studio 2026 Insiders，改为安装 Visual Studio 2026 Community。重新安装并重建项目后，问题消失。

遗憾的是，我仍然不知道确切的根本原因。我的最佳猜测是Insiders版构建或本地开发环境中的某些内容被损坏或配置错误。切换到Community版本后，一切都恢复正常，包括Swagger。

解决方案

The issue is not with Swagger UI itself — it happens because the Swagger JSON endpoint (/swagger/v1/swagger.json) is throwing an internal exception.

In ASP.NET Core, this usually occurs when Swagger tries to generate metadata for controllers and encounters an invalid action.

Root cause

In my case (and commonly), the problem is:

A public method inside a controller that is not a valid API endpoint, for example:

Missing HTTP method attributes ([HttpGet], [HttpPost], etc.)

Helper methods accidentally left as public

Swagger tries to treat all public methods as endpoints and fails during generation.

Fix

Either:

Add the proper HTTP attribute:

[HttpGet]
public IActionResult MyAction() { ... }

OR

Mark non-endpoint methods as ignored:

[NonAction]
public void HelperMethod() { }
How to verify

Open this URL directly in the browser:

/swagger/v1/swagger.json

It will show the actual exception causing the failure.