内置 OpenAPI 与 Scalar UI 实战:practical-aspnetcore 中 minimal-api/open-api-1 的 .NET 10 实践指南
内置 OpenAPI 与 Scalar UI 实战:practical-aspnetcore 中 minimal-api/open-api-1 的 .NET 10 实践指南
本指南以 practical-aspnetcore 仓库中 minimal-api/open-api-1 示例为线索,系统讲解 ASP.NET Core 10 内置 OpenAPI 3.1 支持:如何在完全移除 Swashbuckle/NSwag 等第三方包的前提下,通过 AddOpenApi() 与 XML 文档注释自动生成 OpenAPI 文档,并用现代 Scalar UI 提供交互式 API 文档。读完本文,你将掌握内置 OpenAPI 的最小接入流程、XML 注释与响应码的文档化约定、Results<T1, T2> 联合返回类型的元数据推导,以及从旧式 Swashbuckle 方案迁移到内置方案的完整改造点。
示例定位:零第三方依赖的 OpenAPI 3.1 文档
minimal-api/open-api-1 是仓库 Minimal API 分类(projects/minimal-api/README.md 中归类为 "WithOpenApi - 1")下的核心示例,它演示了 .NET 10 的两个关键变化:
- OpenAPI 3.1 文档自动生成——无需引入任何 OpenAPI 相关第三方包;
- XML 文档注释直接填充 API 描述——取代了以往
.WithOpenApi()的编程式配置。
该示例的目标框架为 net10.0,仓库根目录的 global.json 声明 SDK 版本为 10.0.0(rollForward: major),因此运行本示例需要 .NET 10 SDK 环境。
核心特性清单
按照示例文档(projects/minimal-api/open-api-1/README.md)的说明,该示例具备以下能力:
- 无外部包依赖:已移除 Swashbuckle / NSwag,不再需要
AddEndpointsApiExplorer()、AddSwaggerGen()等扩展; - OpenAPI 3.1 文档自动生成:内置文档生成器从端点元数据与 XML 注释自动产出
openapi3.1 规范的 JSON; - XML 注释填充 API 描述:
<summary>、<param>等注释内容直接进入 OpenAPI 的summary、description字段; - 现代 Scalar UI 交互文档:通过
Scalar.AspNetCore包提供/scalar交互式页面; - AOT 兼容:内置 OpenAPI 基于源生成器(source generators)实现,可配合 Native AOT 发布(这是 README 明确声明的能力,迁移报告 OUT-OF-DATE.md 也将其列为迁移收益之一)。
运行示例与文档查看
启动方式
按示例 README 的说明,在 projects/minimal-api/open-api-1 目录下执行:
dotnet watch run
dotnet watch 会在源码变更时自动重启应用,适合边改边看 OpenAPI 文档的调试场景;也可以直接使用 dotnet run。
文档入口
应用启动后提供两个核心地址:
| 地址 | 用途 |
|---|---|
/scalar |
Scalar 交互式 API 文档界面 |
/openapi/v1.json |
自动生成的 OpenAPI 3.1 JSON 文档 |
示例根路径 / 会渲染一个简单的 HTML 导航页(Program.cs),内置两个链接分别指向上述入口:
app.MapGet("/", () => Results.Content("""
<html>
<head>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" ...>
</head>
<body>
<div class="container">
<ul>
<li><a href="/scalar">Scalar API Documentation</a></li>
<li><a href="/openapi/v1.json">OpenAPI JSON</a></li>
</ul>
</div>
</body>
</html>
""", "text/html"));
源码剖析:内置 OpenAPI 的三步接入
示例 Program.cs 全篇不过 39 行,OpenAPI 相关代码只有三行,却完成了文档生成、端点映射与 UI 挂载三件事:
using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(); // ① 注册内置 OpenAPI 文档生成服务
var app = builder.Build();
app.MapOpenApi(); // ② 挂载 OpenAPI 文档端点(默认 /openapi/{documentName}.json)
app.MapScalarApiReference(); // ③ 挂载 Scalar UI(默认 /scalar)
app.MapGet("/greeting", Hello.GetGreeting);
app.Run();
三个调用的职责与仓库内的对照用法如下:
AddOpenApi():将 OpenAPI 文档生成器注册进 DI 容器。它属于Microsoft.AspNetCore.OpenApi包中Microsoft.Extensions.DependencyInjection命名空间的扩展方法,该包正是 .NET 10 的内置实现(版本10.0.11,见 open-api-1.csproj)。MapOpenApi():把文档端点映射到 HTTP 路由。默认路径为/openapi/{documentName}.json,documentName默认为v1,因此访问/openapi/v1.json。仓库中 net10/open-api-9 展示了自定义路径,甚至可同时映射 JSON 与 YAML 两种格式:app.MapOpenApi("/openapi/{documentName}.json"); app.MapOpenApi("/openapi/{documentName}.yaml");MapScalarApiReference():来自Scalar.AspNetCore(版本2.16.18)的扩展方法,挂载 Scalar 交互式文档界面。
端点本体:XML 注释即文档
示例的业务端点是一个静态方法委托,文档信息全部来自 XML 注释(Program.cs):
public record Person(string Name);
/// <summary>
/// Return greeting given name
/// </summary>
public static class Hello
{
/// <param name="name">The name of the person to greet</param>
public static IResult GetGreeting(string name) => Results.Ok(new Person(name));
}
要点拆解:
<summary>注释会被写入 OpenAPI 操作对象的summary字段,成为端点的一句话说明;<param name="name">注释会填充name参数的描述信息,并让string name这个查询参数自动出现在文档中;- 返回值
Results.Ok(new Person(name))经内置文档生成器推断为200 OK,响应体 Schema 由record Person(string Name)推导(JSON 字段为name,字符串类型); - 值得注意的是示例的
GetGreeting返回IResult(非泛型),因此 200 之外的其他状态码信息不会被自动枚举——这正是下一个示例open-api-2用Results<T1, T2>要解决的问题(详见下文"仓库内进阶对照")。
工程配置:让 XML 注释进入 OpenAPI
示例的 open-api-1.csproj 是迁移的核心载体,完整内容如下:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>true</ImplicitUsings>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.11" />
<PackageReference Include="Scalar.AspNetCore" Version="2.16.18" />
</ItemGroup>
</Project>
三个关键配置项的含义与作用:
| 配置项 | 作用 | 备注 |
|---|---|---|
Microsoft.AspNetCore.OpenApi |
内置 OpenAPI 生成器 | 版本 10.0.11,随 .NET 10 提供 |
Scalar.AspNetCore |
Scalar UI 界面库 | 版本 2.16.18,提供 MapScalarApiReference() |
GenerateDocumentationFile |
编译时输出 XML 文档文件 | 内置 OpenAPI 读取该 XML 填充描述,是"XML 注释即文档"的前提 |
NoWarn 1591 |
抑制"缺少 XML 注释"的编译警告 | 避免未注释成员产生大量 CS1591 警告 |
需要注意:GenerateDocumentationFile 一旦开启,未加注释的公共成员会触发 CS1591 警告,因此示例同时用 <NoWarn>$(NoWarn);1591</NoWarn> 抑制。同类示例(如 net10/open-api-8、net10/open-api-9)也采用了相同的配置模式。
从 Swashbuckle 迁移到内置 OpenAPI
示例 README 明确指出它"从 Swashbuckle 迁移到 .NET 10 内置 OpenAPI 支持",并列出四项变更。仓库根目录的迁移报告 OUT-OF-DATE.md 给出了该迁移模式的"前/后"完整对照,是理解这次改造的最佳教材。
迁移前(Swashbuckle 时代)
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI();
app.MapGet("/greeting", Hello.GetGreeting).WithOpenApi(op => { ... });
迁移后(内置 OpenAPI)
builder.Services.AddOpenApi();
var app = builder.Build();
app.MapOpenApi();
app.MapScalarApiReference();
/// <summary>
/// Return greeting given name
/// </summary>
app.MapGet("/greeting", Hello.GetGreeting);
四项变更逐条对照
按示例 README 的 "Changes" 列表:
- 移除
Swashbuckle.AspNetCore包依赖——不再需要AddSwaggerGen()、UseSwagger()、UseSwaggerUI()这一整套管线; - 加入
Microsoft.AspNetCore.OpenApi(内置)——仅此一个包即提供文档生成能力; - 加入
Scalar.AspNetCore——用现代 UI 替代传统 Swagger UI; - 用 XML 文档注释替换
WithOpenApi()——描述与响应信息从"代码内编程式配置"改为"注释声明式配置";同时必须在 .csproj 中开启GenerateDocumentationFile。
迁移收益
OUT-OF-DATE.md 以表格形式总结了迁移收益:
| 方面 | 迁移前 | 迁移后 |
|---|---|---|
| 依赖 | Swashbuckle.AspNetCore | 内置(无需额外包) |
| OpenAPI 版本 | 3.0 | 3.1 |
| AOT 兼容 | 否 | 是 |
| 代码简洁度 | 样板代码更多 | XML 注释即可 |
| 性能 | 一般 | 更好(源生成器) |
需要说明的是,"性能更好(源生成器)"与"AOT 兼容"是迁移报告声明的结论,属于该仓库记录的官方表述;OpenAPI 版本由 3.0 升至 3.1 则是文档生成器的直接产物(/openapi/v1.json 中 openapi 字段为 3.1.0)。
仓库内进阶对照:文档化的深化路径
围绕 open-api-1 的主题,仓库内还有一组同源示例,从不同角度深化了"XML 注释驱动文档"这一主线,可作为继续阅读的路线图:
- minimal-api/open-api-2:
Results<T1, T2>联合返回类型 +<response>注释。端点的返回类型声明为Results<Ok<Person>, NotFound>,配合<response code="200">与<response code="404">注释,让 OpenAPI 文档同时列出 200 与 404 两种响应及其说明:
这正是对/// <response code="200">Returns the person with the greeting</response> /// <response code="404">If name is null or whitespace</response> public static Results<Ok<Person>, NotFound> GetGreeting(string name) { if (string.IsNullOrWhiteSpace(name)) return TypedResults.NotFound(); return TypedResults.Ok(new Person(name)); }open-api-1中"仅 200 响应"的补强——从源码结构看,联合返回类型是内置文档生成器枚举多个响应状态码的关键信号。 - net10/open-api-10:用
<response code="500">标注错误响应,配合Results<Ok<string>, InternalServerError<string>>展示异常路径的文档化。 - net10/open-api-11:用
<returns>注释填充 200 响应的描述信息。 - net10/open-api-8:
<summary>/<remarks>/<param>三类注释如何分别进入操作的 summary、description 与参数描述。 - net10/open-api-9:同一份文档同时输出 JSON 与 YAML,并演示
UseSwaggerUi对接 YAML 路径。 - minimal-api/map-group-2:
WithTags()/WithDescription()/WithSummary()为路由组批量附加 OpenAPI 元数据。 - minimal-api/map-group-3:
ExcludeFromDescription()将导航页等非 API 端点排除在文档之外(open-api-1的根路径/页面并未排除,属于刻意保留的演示行为;实际项目中建议按此示例排除)。
适用前提与限制
基于仓库实际内容,使用本方案需要明确以下前提:
- 目标框架:内置 OpenAPI 是 .NET 10 的能力,示例
TargetFramework为net10.0,需要 .NET 10 SDK(仓库 global.json 指定10.0.0,并开启rollForward: major与allowPrerelease)。 - 包版本:当前示例锁定
Microsoft.AspNetCore.OpenApi 10.0.11与Scalar.AspNetCore 2.16.18,升级 SDK 时建议同步核对包版本。 - 文档信息源头:描述性信息依赖 XML 注释与编译产物,务必在 .csproj 中开启
GenerateDocumentationFile,并处理好 CS1591 警告。 - 运行方式:本示例为可独立运行的 Minimal API 应用,仅需在
projects/minimal-api/open-api-1目录执行dotnet watch run(或dotnet run)后访问/scalar与/openapi/v1.json即可验证完整效果。