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文档了:

当然只有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+的叠加功能,因此在NET8下是不可用的,如果想赶在年底体验 可以下载VS的最新预览版和NET9的preview4 SDK.

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

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

NET9 AspnetCore将整合OpenAPI的文档生成功能而无需三方库的更多相关文章

  1. Taurus.MVC 2.3 开源发布：增强属性Require验证功能，自带WebAPI文档生成功能

    背景: 上周,把 Taurus.MVC 在 Linux (CentOS7) 上部署任务完成后. 也不知怎么的,忽然就想给框架集成一下WebAPI文档功能,所以就动手了. 以为一天能搞完,结果,好几天过 ...

  2. 【开源】AspnetCore 2.0 自动API文档生成组件，支持protobuffer

    本文地址 http://www.cnblogs.com/likeli/p/8204054.html 关于 API文档自动生成,用于对APP端的开发帮助文档生成,默认ProtoBuffer传输格式. 本 ...

  3. Objective-C规范注释心得——同时兼容appledoc（docset、html）与doxygen（html、pdf）的文档生成

    作者:zyl910 手工写文档是一件苦差事,幸好现在有从源码中抽取注释生成文档的专用工具.对于Objective-C来说,目前最好用的工具是appledoc和doxygen.可是这两种工具对于注释的要 ...

  4. SpringBoot之Swagger2文档生成

    SpringBoot之Swagger2文档生成 1.Swagger2介绍 编写和维护接口文档是每个程序员的职责,前面我们已经写好的接口现在需要提供一份文档,这样才能方便调用者使用.考虑到编写接口文档是 ...

  5. 求你别再用swagger了，给你推荐几个在线文档生成神器

    前言 最近公司打算做一个openapi开放平台,让我找一款好用的在线文档生成工具,具体要求如下: 必须是开源的 能够实时生成在线文档 支持全文搜索 支持在线调试功能 界面优美 说实话,这个需求看起来简 ...

  6. 再见丑陋的 SwaggerUI，这款开源的API文档生成神器界面更炫酷，逼格更高！

    一般在使用 Spring Boot 开发前后端分离项目的时候,都会用到 Swagger.Swagger 是一个规范和完整的框架,用于生成.描述.调试和可视化 RESTful 风格的 Web API 服 ...

  7. 【C#附源码】数据库文档生成工具支持（Excel+Html）

    [2015] 很多时候,我们在生成数据库文档时,使用某些工具,可效果总不理想,不是内容不详细,就是表现效果一般般.很多还是word.html的.看着真是别扭.本人习惯用Excel,所以闲暇时,就简单的 ...

  8. 微软开源全新的文档生成工具DocFX

    微软放弃Sandcastle有些年头了,微软最近开源了全新的文档生成工具DocFX,目前支持C#和VB,类似JSDoc或Sphinx,可以从源代码中提取注释生成文档之外,而且还有语法支持你加入其他的文 ...

  9. DBImport v3.44 中文版发布：数据库数据互导及文档生成工具（IT人员必备）

    前言: 距离上一个版本V3.3版本的文章发布,已经是1年10个月前的事了. 其实版本一直在更新,但也没什么大的功能更新,总体比较稳定,所以也不怎么写文介绍了. 至于工作上的事,之前有半年时间跑去学英语 ...

  10. .NET平台开源项目速览(4).NET文档生成工具ADB及使用

    很久以前就使用ADB这个工具来生成项目的帮助文档.功能强大,在学习一些开源项目的过程中,官方没有提供CHM帮助文档,所以为了快速的了解项目结构和注释.就生成文档来自己看,非常好用.这也是一个学习方法吧 ...

随机推荐

  1. HMS Core 3D Engine助您实现逼真3D渲染效果，构筑大型3D数字世界

    HMS Core 3D Engine是一款高性能.高画质.高可靠的实时3D引擎,旨在帮助开发者制作高品质的3D应用.3D Engine将为您提供可编程渲染管线,多维粒子系统,3D角色与动画,超大地形地 ...

  2. abcde =（ab+cd）的平方

    int i, a, b; for (i = 1000; i < 10000; i++) { a = i / 100; b = i % 100; if ((a + b) * (a + b) == ...

  3. 想学习eTS开发？教你开发一款IQ-EQ测试应用

    原文:https://mp.weixin.qq.com/s/eZgifjirAW58dFCa0W7kSQ,点击链接查看更多技术内容. 开发者Mack基于HarmonyOS的ArkUI框架开发的IQ- ...

  4. 深入探讨下SSR与CSR有啥不同

    随着互联网技术的迅速发展,用户对网页的加载速度和交互体验有了更高的期待.作为开发者,我们常常需要在服务器端渲染(SSR)与客户端渲染(CSR)之间做出选择.这两种渲染方式各有特点,适用于不同的场景和需 ...

  5. 剑指offer11(Java)-旋转数组中的最小值（简单）

    题目: 把一个数组最开始的若干个元素搬到数组的末尾,我们称之为数组的旋转. 给你一个可能存在 重复 元素值的数组 numbers ,它原来是一个升序排列的数组,并按上述情形进行了一次旋转.请返回旋转数 ...

  6. 力扣8(java)-字符串转整数(atoi)（中等）

    题目: 请你来实现一个 myAtoi(string s) 函数,使其能将字符串转换成一个 32 位有符号整数(类似 C/C++ 中的 atoi 函数). 函数 myAtoi(string s) 的算法 ...

  7. InnoDB之UNDO LOG介绍

    简介: undo log是InnoDB事务特性的重要组成部分.当对记录做增删改操作就会产生undo记录,undo记录会记录到单独的表空间中. 本文将从代码层面对undo log进行一个简单的介绍:主要 ...

  8. 六年团队Leader实战秘诀｜程序员最重要的八种软技能

    ​简介:笔者在带团队的六年中发现,程序员们在职场都有一个共同的困扰:"好像写代码都没什么问题了,日常工作基本上都是应付业务需求的开发,好像找不到其他的更大的附加价值了,我应该找一些什么样的发 ...

  9. 云原生微服务的下一站，微服务引擎 MSE 重磅升级

    ​简介:管好微服务,成为云原生时代的新难题. 管好微服务,成为云原生时代的新难题. 从建好微服务到管好微服务,差的虽是一个字,连接起两边的却需要大量的微服务落地经验.因为软件架构的核心挑战是解决业务快 ...

  10. 如何将一棵LSM-Tree塞进NVM

    ​简介: 随着非易失内存产品的商业化推广,我们对于其在云原生数据库中大规模推广的潜力越来越有兴趣.X-Engine是阿里云数据库产品事业部PolarDB新型存储引擎团队研发的一个LSM-tree存储引 ...