Swashbuckle/Swagger + ASP.NET Core：加载API定义失败问题求助

这个问题我之前也碰到过，本质是Swagger在生成API文档时，要求每个控制器方法必须明确绑定对应的HTTP动作（GET/POST/PUT等）。你的ErrorController里的Index方法只加了[Route]特性，没有指定HTTP方法，导致Swagger解析时出现内部错误，没法生成正确的swagger.json。

下面给你两种可行的解决办法，按需选择：

方法一：给方法添加HTTP动作特性 #

这是最直接规范的做法，每个API端点都应该明确对应的HTTP动词。给你的Index方法加上[HttpGet]特性（如果这个错误端点需要接收多种请求方法，也可以用[AcceptVerbs]指定多个）：

public class ErrorController : Controller { 
  [Route("/error")] 
  [HttpGet] // 新增HTTP动作特性
  public IActionResult Index() { 
    return StatusCode(500, new Error("Internal error.")); 
  } 
}

添加后重启应用，Swagger就能正确识别这个端点，swagger.json也能正常生成了。

方法二：让Swagger忽略错误控制器 #

如果这个错误端点只是用于内部错误跳转，不需要出现在API文档里，你可以配置Swagger过滤掉ErrorController：

1. 在Startup.cs的ConfigureServices方法中，给Swagger添加文档过滤器：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    // 注册过滤ErrorController的文档过滤器
    c.DocumentFilter<HideErrorControllerFilter>();
});

2. 定义过滤类HideErrorControllerFilter：

public class HideErrorControllerFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 遍历所有API描述，移除ErrorController的端点
        var pathsToRemove = swaggerDoc.Paths
            .Where(p => p.Value.Operations.Any(o => 
                context.ApiDescriptions.FirstOrDefault(ad => 
                    ad.RelativePath == p.Key.TrimStart('/') && 
                    ad.ActionDescriptor.ControllerName == "Error") != null))
            .Select(p => p.Key)
            .ToList();

        foreach (var path in pathsToRemove)
        {
            swaggerDoc.Paths.Remove(path);
        }
    }
}

这样Swagger生成文档时就会跳过ErrorController，自然不会再出现解析错误。

两种方法都能解决问题，个人更推荐第一种，因为明确HTTP动作是RESTful API的规范，也能让其他开发者清楚这个端点的调用方式。

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