内置 OpenAPI 与 Scalar UI 实战:practical-aspnetcore 中 minimal-api/open-api-1 的 .NET 10 实践指南

原创2026-10-14 18:47:471,688 阅读
文章标签:示例工程

内置 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 的两个关键变化:

  1. OpenAPI 3.1 文档自动生成——无需引入任何 OpenAPI 相关第三方包;
  2. 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 注释自动产出 openapi 3.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" 列表:

  1. 移除 Swashbuckle.AspNetCore 包依赖——不再需要 AddSwaggerGen()、UseSwagger()、UseSwaggerUI() 这一整套管线;
  2. 加入 Microsoft.AspNetCore.OpenApi(内置)——仅此一个包即提供文档生成能力;
  3. 加入 Scalar.AspNetCore——用现代 UI 替代传统 Swagger UI;
  4. 用 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 即可验证完整效果。
登录后查看全文
practical-aspnetcore