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
}步骤 1：安装 NuGet 包 在项目根目录运行命令（或在 Visual Studio 的 NuGet 包管理器中搜索安装）：
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();步骤 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"
}
}步骤 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步骤 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# 代码
});
}步骤 3：修改 launchSettings.json（同上）
"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;
});
});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。