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文檔了:
當然只有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
太帥了,我們只用了幾行代碼就完整的實現文檔工具的所有功能,以後可以有更多的時間摸魚了,不得不為巨硬 點一個大大的贊!
最後呢這屬於NET9+的疊加功能,因此在NET8下是不可用的,如果想趕在年底體驗 可以下載VS的最新預覽版和NET9的preview4 SDK.
另外我也發現當前生成文檔還存在一絲絲BUG,比如MinimalApi返回了ValidationProblem定義,文檔生成器會報錯,後續正式版發佈這些問題應該都會解決~
最後呢,巨硬都把事幹完了,三方庫還有什麼活路
