NET9 AspnetCore將整合OpenAPI的文檔生成功能而無需三方庫

来源:https://www.cnblogs.com/vipwan/p/18210947
-Advertisement-
Play Games

OpenAPI 規範是用於描述 HTTP API 的標準。該標準允許開發人員定義 API 的形狀,這些 API 可以插入到客戶端生成器、伺服器生成器、測試工具、文檔等中。儘管該標準具有普遍性和普遍性,但 ASP.NET Core 在框架內預設不提供對 OpenAPI 的支持。 當前 ASP.NET ...


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) 然後簡單的敲擊以下代碼:

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文檔可能還不夠,我們可以擴展一個ScalarUI掛載文檔,當然有興趣也可以用SwaggerUI :

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定義,文檔生成器會報錯,後續正式版發佈這些問題應該都會解決~

最後呢,巨硬都把事幹完了,三方庫還有什麼活路


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 1 為啥要折騰搭建一個專屬圖床? 技術大佬寫博客都用 md 格式,要在多平臺發佈,圖片就得有外鏈 後續如博客遷移,國內博客網站如掘金,簡書,語雀等都做了防盜鏈,圖片無法遷移 2 為啥選擇CloudFlare R2 跳轉:https://dash.cloudflare.com/ 有白嫖額度 免費 CD ...
  • 實時識別關鍵詞是一種能夠將搜索結果提升至新的高度的API介面。它可以幫助我們更有效地分析文本,並提取出關鍵詞,以便進行進一步的處理和分析。 該介面是挖數據平臺提供的,有三種模式:精確模式、全模式和搜索引擎模式。不同的模式在分詞的方式上有所不同,適用於不同的場景。 首先是精確模式。這種模式會儘量將句子 ...
  • Java JUC&多線程 基礎完整版 目錄Java JUC&多線程 基礎完整版1、 多線程的第一種啟動方式之繼承Thread類2、多線程的第二種啟動方式之實現Runnable介面3、多線程的第三種實現方式之實現Callable介面4、多線的常用成員方法5、線程的優先順序6、守護線程7、線程的讓出8、線 ...
  • 本文介紹基於Python語言,遍歷文件夾並從中找到文件名稱符合我們需求的多個.txt格式文本文件,並從上述每一個文本文件中,找到我們需要的指定數據,最後得到所有文本文件中我們需要的數據的合集的方法~ ...
  • 作為後端工程師,多數情況都是給別人提供介面,寫的好不好使你得重視起來。 最近我手頭一些活,需要和外部公司對接,我們需要提供一個介面文檔,這樣可以節省雙方時間、也可以防止後續扯皮。這是就要考驗我的介面是否規範化。 1. 介面名稱清晰、明確 顧名思義,介面是做什麼的,是否準確、清晰?讓使用這一眼就能知道 ...
  • SpringBoot筆記 SpringBoot文檔 官網: https://spring.io/projects/spring-boot 學習文檔: https://docs.spring.io/spring-boot/docs/current/reference/html/ 線上API: http ...
  • 一、背景說明 1.1 效果演示 用python開發的爬蟲採集軟體,可自動抓取抖音評論數據,並且含二級評論! 為什麼有了源碼還開發界面軟體呢?方便不懂編程代碼的小白用戶使用,無需安裝python、無需懂代碼,雙擊打開即用! 軟體界面截圖: 爬取結果截圖: 以上。 1.2 演示視頻 軟體運行演示視頻:見 ...
  • @DateTimeFormat 和 @JsonFormat 是 Spring 和 Jackson 中用於處理日期時間格式的註解,它們有不同的作用: @DateTimeFormat @DateTimeFormat 是 Spring 框架提供的註解,用於指定字元串如何轉換為日期時間類型,以及如何格式化日 ...
一周排行
    -Advertisement-
    Play Games
  • 一:背景 1. 講故事 前些天有位朋友找到我,說他們的程式會偶發性的卡死一段時間,然後又好了,讓我幫忙看下怎麼回事?窗體類的程式解決起來相對來說比較簡單,讓朋友用procdump自動抓一個卡死時的dump,拿到dump之後,上 windbg 說話。 二:WinDbg 分析 1. 主線程在做什麼 要想 ...
  • 功能說明 使用ListView時,希望可以在單元格顯示圖片或其他控制項,發現原生的ListView不支持,於是通過拓展,實現ListView可以顯示任意控制項的功能,效果如下: 實現方法 本來想著在單元格裡面實現控制項的自繪的,但是沒找到辦法,最後是通過在單元格的錶面顯示對應控制項的,浮於錶面達到目的。 實 ...
  • 由於.NET Framework 4.0 是比較古老的版本,只有New Relic 7.0以下的版本才會支持.NET Framework 4.0的引用程式。 Technical support for .NET Framework 4.0 or lower 你可以參考這個官方Install New ...
  • 前言 隨著 DEV24.1.3 的發佈,XAF Blazor 中的屬性編輯器(PropertyEditor)也進行了很大的改動,在使用體驗上也更接近 WinForm 了,由於進行了大量的封裝,理解上沒有 WinForm 直觀,所以本文通過對屬性編輯器的原理進行解析,並對比新舊版本中的變化,使大家能夠 ...
  • OPC基金會提供了OPC UA .NET標準庫以及示常式序,但官方文檔過於簡單,光看官方文檔和示常式序很難弄懂OPC UA .NET標準庫怎麼用,花了不少時間摸索才略微弄懂如何使用,以下記錄如何從一個控制台程式開發一個OPC UA伺服器。 安裝Nuget包 安裝OPCFoundation.NetSt ...
  • 今天在技術群里,石頭哥向大家提了個問題:"如何在一個以System身份運行的.NET程式(Windows Services)中,以其它活動的用戶身份啟動可互動式進程(桌面應用程式、控制台程式、等帶有UI和互動式體驗的程式)"? 我以前有過類似的需求,是在GitLab流水線中運行帶有UI的自動化測試程 ...
  • .Net 中提供了一系列的管理對象集合的類型,數組、可變列表、字典等。從類型安全上集合分為兩類,泛型集合 和 非泛型集合,傳統的非泛型集合存儲為Object,需要類型轉。而泛型集合提供了更好的性能、編譯時類型安全,推薦使用。 ...
  • 在以前我做程式的時候,一般在登錄視窗裡面顯示程式名稱,登錄視窗一般設置一張背景圖片,由於程式的名稱一般都是確定的,所以也不存在太大的問題,不過如果客戶定製不同的系統的時候,需要使用Photoshop修改下圖層的文字,再生成圖片,然後替換一下也可以了。不過本著減少客戶使用繁瑣性,也可以使用空白名稱的通... ...
  • 一:背景 1. 講故事 在dump分析的過程中經常會看到很多線程卡在Monitor.Wait方法上,曾經也有不少人問我為什麼用 !syncblk 看不到 Monitor.Wait 上的鎖信息,剛好昨天有時間我就來研究一下。 二:Monitor.Wait 底層怎麼玩的 1. 案例演示 為了方便講述,先 ...
  • 目錄前言學習參考過程總結: 前言 做個自由仔。 學習參考 ChatGpt; https://www.cnblogs.com/zhili/p/DesignPatternSummery.html(大佬的,看了好多次) 過程 原由: 一開始只是想查查鏈式調用原理,以為是要繼承什麼介面,實現什麼方法才可以實 ...