使用Swashbuckle生成Swagger时无端点显示的问题排查

你遇到的核心问题是控制器方法不符合ASP.NET Core路由系统的识别规则，再加上几个小细节影响了Swagger的扫描，下面逐个说明并给出修复方案：

1. 移除控制器方法的static修饰符（最关键） #

ASP.NET Core的路由系统只会识别控制器实例的成员方法，静态方法不会被注册到路由表中，这直接导致Swagger扫描不到你的端点。

看你的代码：

[HttpGet("{id}")]
public static Task<Result> GetSomething(string id) {
    return new Task<Result>(null, "");
}

把static去掉，改成实例方法：

[HttpGet("{id}")]
public Task<Result> GetSomething(string id) {
    // 注意：原Task创建方式错误，下文会修正
    return Task.FromResult(new Result(null, ""));
}

2. 改用ControllerBase作为API控制器的基类 #

你的ApiController继承自Controller，这个基类是为MVC视图场景设计的，包含很多视图相关的成员。对于纯API服务，更推荐使用ControllerBase——它是专门为API控制器设计的轻量化基类，能避免不必要的干扰：

public class ApiController : ControllerBase

3. 修正路由模板的冗余斜杠 #

控制器上的路由[Route("api/MyApi/v1/")]末尾多了一个斜杠，虽然路由系统会自动处理，但规范写法是去掉它，保持路由模板的简洁：

[Route("api/MyApi/v1")]

修改后和[HttpGet("{id}")]组合，最终的路由是api/MyApi/v1/{id}，符合RESTful规范。

4. 修复Task的错误创建方式 #

你代码里new Task<Result>(null, "")是错误的Task构造用法，这样创建的任务永远不会进入完成状态。如果是同步逻辑需要包装成Task，应该用Task.FromResult；如果是真正的异步操作，使用await关键字：

// 同步逻辑包装成Task的正确写法
public Task<Result> GetSomething(string id) {
    return Task.FromResult(new Result { 
        // 这里根据你的Result类定义初始化属性
    });
}

// 异步逻辑示例（如果有实际异步操作）
public async Task<Result> GetSomething(string id) {
    // 比如调用异步数据库操作或第三方服务
    var resultData = await _someDependency.FetchDataAsync(id);
    return new Result { Data = resultData };
}

5. 确保XML注释文件正确生成 #

你在Swagger配置中启用了XML注释扫描，要确保项目已经开启了XML文档生成：

• 右键项目 → 属性 → 生成 → 勾选“XML文档文件”，保持默认路径即可（生成和程序集同名的.xml文件）。
  如果没有生成这个文件，虽然不会导致端点消失，但会丢失接口注释，还可能在日志中出现警告。

完成以上修改后，重新启动项目，Swagger应该就能正确识别并展示你的GetSomething端点了。

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