.NET Core 2.1迁移后Swagger UI无API文档显示求助

我来帮你排查这个Swagger无法显示API的问题，结合你提供的.csproj和部分Startup代码，下面是几个针对性的解决方案：

1. 升级Swashbuckle版本适配.NET Core 2.1 #

你当前使用的Swashbuckle.AspNetCore 2.4.0和.NET Core 2.1存在兼容性问题——这个版本对2.1新增的[ApiController]特性支持不完善，是导致接口无法被扫描到的常见原因。建议升级到2.5.0及以上版本（2.5.0是专门适配.NET Core 2.1的第一个稳定版本）。

修改你的.csproj中的PackageReference：

<PackageReference Include="Swashbuckle.AspNetCore" Version="2.5.0" />
<PackageReference Include="Swashbuckle.AspNetCore.ReDoc" Version="2.5.0" />

2. 确保控制器符合[ApiController]的路由要求 #

.NET Core 2.1的[ApiController]特性强制要求使用属性路由，不能依赖传统的约定式路由。如果你的控制器没有添加[Route]特性，Swagger将无法识别到接口。

检查你的控制器类，必须配置类似这样的路由模板：

[ApiController]
[Route("api/[controller]")] // 或自定义符合业务需求的路由
public class YourController : ControllerBase
{
    [HttpGet]
    public IActionResult GetList()
    {
        // 接口逻辑
    }
}

同时在Startup的ConfigureServices中，要明确指定Mvc的兼容版本：

services.AddMvc()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

3. 确认Swagger配置加载了XML注释文件 #

你的.csproj已经配置生成XML文档，但如果Startup里没有将这个文件引入Swagger，可能会导致接口无法被正确扫描（尤其是依赖注释生成文档的场景）。

在Startup的ConfigureServices中添加Swagger配置时，务必包含XML注释加载逻辑：

using System.Reflection;
using System.IO;

// ...

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Administration API", Version = "v1" });
    
    // 加载当前程序集的XML注释文件
    var xmlFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    c.IncludeXmlComments(xmlFilePath);
});

4. 排查其他可能的扫描阻碍 #

• 确保控制器继承自ControllerBase（而非旧版的Controller），这是2.1中[ApiController]的推荐基类；
• 彻底移除所有旧版Swagger相关属性（比如旧的[SwaggerOperation]、[SwaggerIgnore]等注解）；
• 如果控制器在其他程序集，需要额外添加对应程序集的XML注释加载逻辑。

5. 确认Swagger中间件正确启用 #

检查Startup的Configure方法中，是否正确添加了Swagger相关中间件：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Administration API V1");
});

最后，清理项目的bin和obj文件夹，重新编译运行，应该就能看到API接口了。

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