NET9 AspnetCore将整合OpenAPI的文档生成功能而无需三方库

net9,aspnetcore,openapi · 浏览次数 : 0

小编点评

** OpenAPI 规范的定义** OpenAPI 规范是一个用于描述 HTTP API 的标准格式,允许开发人员定义 API 的形状。 **ASP.NET Core 中对 OpenAPI 的支持** ASP.NET Core 默认不提供对 OpenAPI 的内置支持。然而,可以使用第三方库或 API 实现对 OpenAPI 的支持。 **微软提供的 OpenAPI 文档生成** 在 .NET 9 版本中,微软提供了一种用于生成 ASP.NET Core API 的 OpenAPI 文档的功能。这功能允许开发人员通过 VS 的 OpenAPI 文档工具访问和生成 API 文档。 **如何生成 OpenAPI 文档** 1. 创建一个 ASP.NET Core WebApi 项目。 2. 引用 `Microsoft.AspNetCore.OpenApi` 库。 3. 使用 `builder.Services.AddOpenApi()` 注册 OpenAPI 支持。 4. 使用 `MapOpenApi()` 方法添加 API 路由。 5. 使用 `WithOpenApi()` 方法配置 OpenAPI 配置。 6. 访问 `~/openapi/v1.json` 即可查看生成的 OpenAPI 文档。 **示例代码** ```csharp // Configure OpenApi services.AddOpenApi(); // Map API routes app.MapOpenApi(); // Generate OpenAPI document var summaries = new[] { /* OpenAPI metadata here */ }; app.MapGet("/weatherforecast", () => { var forecast = Enumerable.Range(1, 5).Select(...); return forecast; }); // Register UI for OpenAPI documentation app.MapScalarUi(); ```

正文

OpenAPI 规范是用于描述 HTTP API 的标准。该标准允许开发人员定义 API 的形状,这些 API 可以插入到客户端生成器、服务器生成器、测试工具、文档等中。尽管该标准具有普遍性和普遍性,但 ASP.NET Core 在框架内默认不提供对 OpenAPI 的支持。

当前 ASP.NET Core 不提供对 OpenAPI 的内置支持。不过内置支持了 ApiExplorer 这是一个有用的抽象,它提供有关在应用程序中注册的路由的元数据。此元数据可通过 DI 容器访问,并由生态系统中的工具(如 Asp.Api.Versioning、NSwag 和 Swashbuckle)通过ApiExplorer查询聚合的metadata

在 .NET 6 中,引入了Minimal Api,并通过 EndpointMetadataApiDescriptionProvider 添加了对Minimal Api的支持,这允许ApiExplorer查询metadata并注册这些api的Endpoint。

在 .NET 7 中,引入了Microsoft.AspNetCore.OpenApi(注意:此包通过 NuGet 提供,不是shared framework 成员)。WithOpenApi扩展 公开了用于修改Minimal API 中与单个Endpoint关联的扩展方法。该包依赖于 Microsoft.OpenApi 包,提供对象模型和反序列化程序/序列化程序,用于与各种版本的 OpenAPI 规范进行交互。

为了解决三方库兼容的问题并为用户提供更无缝的体验,在NET9以后的版本中,AspnetCore团队将OpenAPI文档生成作为 ASP.NET Core 的内置功能。

我们用VS最新预览版创建一个NET9的 WebApi项目 名为SwaggerBye (#.#),引用Microsoft.AspNetCore.OpenApi库 然后简单的敲击以下代码:

builder.Services.AddOpenApi();
var app = builder.Build();
app.MapOpenApi();//生成文档的Endpoint

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapGet("/weatherforecast", () =>
    {
        var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                (
                    DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                    Random.Shared.Next(-20, 55),
                    summaries[Random.Shared.Next(summaries.Length)]
                ))
            .ToArray();
        return forecast;
    })
    .WithName("GetWeatherForecast")
    .WithOpenApi();

app.MapMethods("hello/{world}", ["GET"],
    (string world) => { return Results.Json(new HelloDto(world)); })
    .WithOpenApi()
    .Produces<HelloDto>(200);

然后我们访问 ~/openapi/v1.json 就可以看到生成的scheme文档了:
image

当然只有Scheme文档可能还不够,我们可以扩展一个UI挂载文档:

public static IEndpointConventionBuilder MapScalarUi(this IEndpointRouteBuilder endpoints)
{
	return endpoints.MapGet("/scalar/{documentName}", (string documentName) => Results.Content($$"""
<!doctype html>
<html>
<head>
<title>Scalar API Reference -- {{documentName}}</title>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1" />
</head>
<body>
<script
id="api-reference"
data-url="/openapi/{{documentName}}.json"></script>
<script>
var configuration = {
theme: 'purple',
}

document.getElementById('api-reference').dataset.configuration =
JSON.stringify(configuration)
</script>
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
</body>
</html>
""", "text/html")).ExcludeFromDescription();
}

然后调用MapScalarUi()扩展

if (app.Environment.IsDevelopment())
{
    app.MapScalarUi();
}

最后我们访问 ~/scalar/v1
image

太帅了,我们只用了几行代码就完整的实现文档工具的所有功能,以后可以有更多的时间摸鱼了,不得不为巨硬 点一个大大的赞!

最后呢这属于NET9+的叠加功能,因此在NET8下是不可用的,如果想赶在年底体验 可以下载VS的最新预览版和NET9的preview4 SDK.

另外我也发现当前生成文档还存在一丝丝BUG,比如MinimalApi返回了ValidationProblem定义,文档生成器会报错,后续正式版发布这些问题应该都会解决~

最后呢,微软是在走别人的路让别人无路可走 , 我们有没有发现,现在STJ成为了顶级成员Newtonsoft.Json慢慢被遗忘,MS DI横空出世 Autofac就黯然落幕,现在Microsoft.AspNetCore.OpenApi整合了对OpenApi的完整支持,那NSwag和Swashbuckle也将被遗弃,对于一般开发者而言可能是好事,但是这些曾经风光的开源项目就慢慢被历史遗忘,确实有些遗憾~

与NET9 AspnetCore将整合OpenAPI的文档生成功能而无需三方库相似的内容:

NET9 AspnetCore将整合OpenAPI的文档生成功能而无需三方库

OpenAPI 规范是用于描述 HTTP API 的标准。该标准允许开发人员定义 API 的形状,这些 API 可以插入到客户端生成器、服务器生成器、测试工具、文档等中。尽管该标准具有普遍性和普遍性,但 ASP.NET Core 在框架内默认不提供对 OpenAPI 的支持。 当前 ASP.NET

NET9 提供HybridCache解决分布式缓存中存在的远程链接&序列化带来的性能问题

下面是一个标准的IDistributedCache用例: public class SomeService(IDistributedCache cache) { public async Task GetSomeInformationAsync (string na

WPF在.NET9中的重大更新:Windows 11 主题

在2023年的2月20日,在WPF的讨论区,WPF团队对路线的优先级发起了一次讨论。 对三个事项发起了投票。 第一个是Windows 11 主题 第二个是更新的控件 第三个是可空性注释 最终Windows 11 主题得票最高,WPF团队2023-2024的工作优先级就是Windows 11 主题了。

.NET 9 预览版6发布

微软发布了 .NET 9 的第 6 个预览版,此版本包括对运行时、SDK、.NET MAUI、ASP.NET Core 和 C# 的更新,预览版没有包含太多新的主要功能或特性,因为已接近 .NET 9 开发的最后阶段,该开发计划于 11 月全面发布。Loongarch的Native-AOT代码合进去

.NET 9 预览版 5 发布

微软在6月发布了.NET 9预览版的第五个版本。这个新版本的框架预计将在今年晚些时候正式发布,它是一个标准支持(STS)版本,将在2024年11月12日至2026年5月12日期间在多个操作系统上获得18个月的支持。这个预览版带来了性能改进和一些新特性,例如增强的AI能力、优先级无界通道、Search

C# 13(.Net 9) 中的新特性 - 扩展类型

C# 13 即 .Net 9 按照计划会在2024年11月发布,目前一些新特性已经定型,今天让我们来预览一个比较大型比较重要的新特性: 扩展类型 extension types

本计划在 .NET 8 中推出的 WASI 推迟到 .NET 9

本计划在 .NET 8 中推出的 WASI 已推迟到 .NET 9,请参阅 Github 上的 WASI 跟踪问题。 在.NET 8 Preview 4 开始支持生成与 WASI 兼容的 .wasm 文件,使用独立的 WebAssembly 运行时 Wasmtime CLI[1] 运行该文件。去年的

微软在Microsoft Build 2024 上 发布了.NET 9 预览版4

在 Microsoft Build 2024 上,与往年一样,.NET 不是会议主题演讲的主题,但是微软在这个大会上为.NET 推出一组新的功能和工具,旨在使 .NET 开发更快、更轻松,具体内容可以阅读文章:Microsoft Build 2024 的 .NET 公告和更新[1]。最新功能都在.N