.NET 9 中 OpenAPI 替代 Swagger 文档生成

微软已经放弃了对 .NET 9 中 Swagger UI 包 Swashbuckle 的支持。他们声称该项目“不再由社区所有者积极维护”并且“问题尚未得到解决”。

这意味着当您使用 .NET 9 模板创建 Web API 时，您将不再拥有 UI 来测试您的 API 端点。

我们将调查是否可以在 .NET 9 中使用 Swagger UI 以及是否有更好的替代方案。

在本文中，我们将深入探讨微软在 .NET 9 中引入的开放 API 支持。此支持使应用程序的客户可以方便地理解和编写相应的 API 调用，并轻松与我们的自动 HTTP 客户端代码生成工具（如 Swagger）集成。

什么是开放 API？
OpenAPI 规范是定义 HTTP API 的广泛接受的标准。它可以帮助开发人员概述 API 的结构，使其更容易与客户端和服务器生成器、测试框架、文档系统等工具集成。借助 .NET 9，ASP.NET Core 现在内置了对基于控制器和最小 API 生成 OpenAPI 文档的支持，这要归功于 Microsoft.AspNetCore.OpenApi 包。

如何使用它？

这是一个基本的 ASP.NET Core 9 项目示例，演示了如何将 OpenAPI 支持集成到 Program.cs 中。我们已经准备好了所需的设置。

builder.Services.AddOpenApi();//这将添加依赖项
app.MapOpenApi();//这将注册一个端点

自定义

以下代码更新 Open API 文档端点路径。始终确保路径遵循约定为“<pathtodocument>.json”。

app.MapOpenApi("/openapidocument.json");

下面的代码更新了文档的描述，将授权标头标记为必需，并添加了一个额外的服务器作为文档的一部分。

builder.Services.AddOpenApi(options =>
{
options.AddDocumentTransformer((document, context, cancellationToken) =>
{
document.Info.Description = "This is open api demo";

// Add when authorization headers are required
var authComponent = new OpenApiComponents
{
Headers = new Dictionary<string, OpenApiHeader>
{
{ "Authorization", new OpenApiHeader { Required = true } }
}
};
document.Components = authComponent;

// Add new server if app is available at multiple locations
document.Servers.Add(new OpenApiServer
{
Url = "https://appdev.com/",
Description = "This is dev server"
});

return Task.CompletedTask;
});
});

以下是我们最终的开放 API JSON，可在“https://localhost:7283/openapidocument.json”上找到。

{
"openapi": "3.0.1",
"info": {
"title": "OpenAPIDemo | v1",
"description": "This is open api demo",
"version": "1.0.0"
},
"servers": [
{
"url": "https://localhost:7283"
},
{
"url": "http://localhost:5196"
},
{
"url": "https://appdev.com/",
"description": "This is dev server"
}
],
"paths": {
"/WeatherForecast": {
"get": {
"tags": [
"WeatherForecast"
],
"operationId": "GetWeatherForecast",
"responses": {
"200": {
"description": "OK",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WeatherForecast"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WeatherForecast"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WeatherForecast"
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"WeatherForecast": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"temperatureC": {
"type": "integer",
"format": "int32"
},
"temperatureF": {
"type": "integer",
"format": "int32"
},
"summary": {
"type": "string",
"nullable": true
}
}
}
},
"headers": {
"Authorization": {
"required": true
}
}
},
"tags": [
{
"name": "WeatherForecast"
}
]
}