翼度科技»论坛 编程开发 .net 查看内容

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

6

主题

6

帖子

18

积分

新手上路

Rank: 1

积分
18
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 规范进行交互。
为了解决三方库兼容的问题并为用户提供更无缝的体验(当前三方库还用ntj处理JSON序列化,估计这个微软就不能忍),在NET9以后的版本中,AspnetCore团队将OpenAPI文档生成作为 ASP.NET Core 的内置功能。
我们用VS最新预览版创建一个NET9的 WebApi项目 名为SwaggerBye (#.#),引用Microsoft.AspNetCore.OpenApi库(当前最新的预览版是:9.0.0-preview.4.24267.6) 然后简单的敲击以下代码:
  1. builder.Services.AddOpenApi();
  2. var app = builder.Build();
  3. app.MapOpenApi();//生成文档的Endpoint
  4. var summaries = new[]
  5. {
  6.     "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
  7. };
  8. app.MapGet("/weatherforecast", () =>
  9.     {
  10.         var forecast = Enumerable.Range(1, 5).Select(index =>
  11.                 new WeatherForecast
  12.                 (
  13.                     DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
  14.                     Random.Shared.Next(-20, 55),
  15.                     summaries[Random.Shared.Next(summaries.Length)]
  16.                 ))
  17.             .ToArray();
  18.         return forecast;
  19.     })
  20.     .WithName("GetWeatherForecast")
  21.     .WithOpenApi();
  22. app.MapMethods("hello/{world}", ["GET"],
  23.     (string world) => { return Results.Json(new HelloDto(world)); })
  24.     .WithOpenApi()
  25.     .Produces<HelloDto>(200);
复制代码
然后我们访问 ~/openapi/v1.json 就可以看到生成的scheme文档了:

当然只有Scheme文档可能还不够,我们可以扩展一个ScalarUI挂载文档,当然有兴趣也可以用SwaggerUI :
  1. public static IEndpointConventionBuilder MapScalarUi(this IEndpointRouteBuilder endpoints)
  2. {
  3.         return endpoints.MapGet("/scalar/{documentName}", (string documentName) => Results.Content($$"""
  4. <!doctype html>
  5. <html>
  6. <head>
  7. <title>Scalar API Reference -- {{documentName}}</title>
  8. <meta charset="utf-8" />
  9. <meta
  10. name="viewport"
  11. content="width=device-width, initial-scale=1" />
  12. </head>
  13. <body>
  14. </body>
  15. </html>
  16. """, "text/html")).ExcludeFromDescription();
  17. }
复制代码
然后调用MapScalarUi()扩展
  1. if (app.Environment.IsDevelopment())
  2. {
  3.     app.MapScalarUi();
  4. }
复制代码
最后我们访问 ~/scalar/v1

太帅了,我们只用了几行代码就完整的实现文档工具的所有功能,以后可以有更多的时间摸鱼了,不得不为巨硬 点一个大大的赞!
最后呢这属于NET9+的叠加功能,因此在NET8下是不可用的,如果想赶在年底体验 可以下载VS的最新预览版和NET9的preview4 SDK.
另外我也发现当前生成文档还存在一丝丝BUG,比如MinimalApi返回了ValidationProblem定义,文档生成器会报错,后续正式版发布这些问题应该都会解决~
最后呢,巨硬都把事干完了,三方库还有什么活路

来源:https://www.cnblogs.com/vipwan/p/18210947
免责声明:由于采集信息均来自互联网,如果侵犯了您的权益,请联系我们【E-Mail:cb@itdo.tech】 我们会及时删除侵权内容,谢谢合作!

本帖子中包含更多资源

您需要 登录 才可以下载或查看,没有账号?立即注册

x

举报 回复 使用道具