在.NET 10 WebAPI 项目中恢复启用 Swagger, 但.NET 10 更加推荐使用Scalar UI

Swagger 在 .NET 10 LTS 中默认不见了

从 .NET 9 开始（.NET 10 完全延续），Microsoft 在 ASP.NET Core Web API 项目模板中移除了 Swashbuckle.AspNetCore 的默认依赖。以前的模板会自动添加 Swashbuckle 并配置 Swagger UI，现在改为内置 OpenAPI 支持（Microsoft.AspNetCore.OpenApi 包）。

新模板默认只会生成 OpenAPI 规范的 JSON 文档（位于 /openapi/v1.json），不再包含交互式 Swagger UI。这是 Microsoft 的有意设计：减少对第三方包的依赖、更好地支持 Minimal API 和 Native AOT，同时转向更原生的 OpenAPI 3.1 规范。

1. 使用内置 OpenAPI 生成文档 + 手动添加 Swagger UI

项目创建后你会看到 Program.cs 里默认已有：

builder.Services.AddOpenApi();   // 注册 OpenAPI 服务

// 在开发环境下
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();   // 暴露 /openapi/v1.json
}

builder.Services.AddOpenApi();   // 注册 OpenAPI 服务

// 在开发环境下
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();   // 暴露 /openapi/v1.json
}

步骤 1：安装 NuGet 包 在项目根目录运行命令（或在 Visual Studio 的 NuGet 包管理器中搜索安装）：

dotnet add package Swashbuckle.AspNetCore.SwaggerUi

dotnet add package Swashbuckle.AspNetCore.SwaggerUi

步骤 2：修改 Program.cs 替换/添加开发环境的代码（完整示例）：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();   // 保持模板默认的这一行

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();   // 暴露 OpenAPI JSON

    // ===== 新增：启用 Swagger UI =====
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "My API v1");  // 指向内置文档
        // 可选：自定义标题、排序等
        // options.DocumentTitle = "我的 WebAPI 文档";
        // options.DefaultModelsExpandDepth = -1; // 折叠模型
    });
}

app.Run();

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();   // 保持模板默认的这一行

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();   // 暴露 OpenAPI JSON

    // ===== 新增：启用 Swagger UI =====
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "My API v1");  // 指向内置文档
        // 可选：自定义标题、排序等
        // options.DocumentTitle = "我的 WebAPI 文档";
        // options.DefaultModelsExpandDepth = -1; // 折叠模型
    });
}

app.Run();

步骤 3：配置启动时自动打开 Swagger 打开 Properties/launchSettings.json，修改 https 配置项（推荐）：

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "launchUrl": "swagger",          // ← 关键：自动打开 /swagger
  "applicationUrl": "https://localhost:7284;http://localhost:5155",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  }
}

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "launchUrl": "swagger",          // ← 关键：自动打开 /swagger
  "applicationUrl": "https://localhost:7284;http://localhost:5155",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  }
}

步骤 4：运行测试 dotnet run 或 F5 启动项目 → 浏览器自动打开 https://localhost:xxxx/swagger。 你会看到熟悉的 Swagger UI，所有 Controller/Minimal API 自动被识别。

2. 使用 Scalar UI（界面更漂亮、功能更丰富、支持 AI 提示、客户端代码生成等）

Scalar 是目前社区和 Microsoft 文档里最推崇的 UI，界面现代化、响应更快、支持主题切换和客户端代码生成。

步骤 1：安装包

dotnet add package Scalar.AspNetCore

dotnet add package Scalar.AspNetCore

步骤 2：修改 Program.cs

using Scalar.AspNetCore;   // 别忘了 using

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    // ===== 新增：启用 Scalar =====
    app.MapScalarApiReference(options =>
    {
        options
            .WithTitle("My API")
            .WithTheme(ScalarTheme.Kepler)      // 可选主题
            .WithDarkModeToggle(true)
            .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient); // 生成 C# 代码
    });
}

using Scalar.AspNetCore;   // 别忘了 using

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    // ===== 新增：启用 Scalar =====
    app.MapScalarApiReference(options =>
    {
        options
            .WithTitle("My API")
            .WithTheme(ScalarTheme.Kepler)      // 可选主题
            .WithDarkModeToggle(true)
            .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient); // 生成 C# 代码
    });
}

步骤 3：修改 launchSettings.json（同上）

"launchUrl": "scalar"   // 或 "scalar/v1"

"launchUrl": "scalar"   // 或 "scalar/v1"

步骤 4：运行 启动后访问 /scalar，体验比 Swagger UI 更现代

额外提示（生产环境与进阶）

1.生产环境：永远不要暴露 OpenAPI/UI（if (app.Environment.IsDevelopment()) 已经做了保护）。

2.自定义文档：可以用 Transformer 增强文档（标题、描述、安全方案等），示例：

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, token) =>
    {
        doc.Info.Title = "我的 WebAPI";
        doc.Info.Version = "v1";
        return Task.CompletedTask;
    });
});

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, token) =>
    {
        doc.Info.Title = "我的 WebAPI";
        doc.Info.Version = "v1";
        return Task.CompletedTask;
    });
});

3. 如果想完全用 Swashbuckle（不推荐）：可以移除 Microsoft.AspNetCore.OpenApi 包，然后安装完整 Swashbuckle.AspNetCore 并用 AddSwaggerGen + UseSwagger + UseSwaggerUI，但会丢失 .NET 10 内置的 OpenAPI 3.1 和 Native AOT 优势。

4. 测试 API：即使不用 UI，也可以用 Visual Studio 的 Endpoints Explorer 或直接访问 /openapi/v1.json 导入 Postman。