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

  • NET9 AspnetCore将整合OpenAPI的文档生成功能而无需三方库已关闭评论
  • 78 次浏览
  • A+
所属分类：.NET技术
摘要

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

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文档了:
NET9 AspnetCore将整合OpenAPI的文档生成功能而无需三方库

当然只有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
NET9 AspnetCore将整合OpenAPI的文档生成功能而无需三方库

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

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

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

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

便宜好用的国外VPS推荐