体验 dotnet 9 中的 OpenAPI 支持
Intro
asp.net 9 中引入了生成 OpenAPI 文档的支持，来体验一下
Get Started
首先我们需要添加对 Microsoft.AspNetCore.OpenApi 的 NuGet 包引用，然后就可以开始改造代码了
var builder = WebApplication.CreateSlimBuilder(args);
//
builder.Services.AddOpenApi();
var app = builder.Build();
//
app.MapOpenApi();
//...
添加 AddOpenApi() 来注册需要的服务，添加 MapOpenApi() 来注册获取 OpenAPI 文档的 endpoint，这样我们就可以访问默认的 /openapi/v1 来查看生成的 OpenAPI 文档了，访问 /openapi/v1.json 应该就可以看到类似下面这样的输出
OpenAPI UI
生成了 OpenAPI 文档之后，我们可以借助 Swagger UI 框架来根据 openapi 文档来显式 OpenAPI 调试界面，我们可以使用原有的 UI 框架，指定好新的 /openapi/v1.json 路径即可
比如说我们使用原来的 Swashbuckle Swagger UI，可以自定义 UI options
app.UseSwaggerUI(option =>
{
option.SwaggerEndpoint("/openapi/v1.json", "OpenAPI V1 Docs");
option.RoutePrefix = string.Empty;
option.DocumentTitle = "SparkTodo API";
});
这样我们就可以使用 Swashbuckle Swagger UI 来展示我们的 API 了，效果和使用 Swashbuckle Swagger 生成 openapi 文档基本一致，只是对于 OpenAPI 文档自定义的支持有所不同
在 dotnetconf 2024 的 session 分享上，展示了另外一个 swagger UI 的选项 -- scalar
在 dotnet 9 还没正式发布的时候有注意到 OpenAPI 功能主要开发贡献的 Safia 就有向这个项目贡献 dotnet 的支持
我们来看下集成 scalar ui，首先添加 Scalar.AspNetCore NuGet 包引用，在原来集成 OpenApi 的基础上，需要添加对 scalar endpoint 的注册
var builder = WebApplication.CreateSlimBuilder(args);
//
builder.Services.AddOpenApi();
var app = builder.Build();
//
app.MapOpenApi();
app.MapScalarApiReference();
//...
注册好之后允许访问 /scalar/v1 即可看到 UI，效果如下：
另外一个 API 的 ui 效果如下
注意截图的话可以看到，这个默认请求示例是 cURL，也支持很多其他的方式，包括很多编程语言，还有一个 httpie，httpie 相比 cURL 会非常的简洁，经常使用 httpie 来测试一些比较简单的 API，我也写了一个 dotnet 版本的 dotnet-httpie 感兴趣的朋友可以去 Github 查看更多示例：https://github.com/WeihanLi/dotnet-httpie
除了使用 dotnet 9 生成的 OpenApi 文档，也支持结合 Swashbuckle Swagger / NSwag 等使用，具体可以参考 scalar 的文档
More
从目前的使用来看，scalar ui 简单的使用还是比较方便的，支持多种语言，
相对来说，但是和 Swashbuckle 相比有些功能还是不太完善的 ，比如说多文档的支持，目前 scalar-ui 对于多文档的支持还有些 bug 而且 UI 不支持像 Swashbuckle Swagger UI 一样在一个页面切换不同的 OpenApi 文档，对于需要一个页面展示多个 openapi 文档的需求 scalar 暂时不支持, 可以仍然使用 Swashbuckle Swagger UI ，大家可以根据能否满足项目需要进行选用
另外目前 OpenApi 的支持不是特别完善, 有位大佬写了一些 OpenApi 的扩展以支持 xml 文档注释等, 输出 yaml 以及设置 example 等, 具体实现可以参考大佬的开源项目源码 https://github.com/martincostello/openapi-extensions, 有一些功能会在 dotnet 10 里支持, 大家有需要在 dotnet 9 里需要这些功能的可以先用大佬的轮子
我们也可以根据需要类似地通过 OpenApi 的 transformer 接口进行扩展, 具体可以参考 https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/customize-openapi?view=aspnetcore-9.0, 或者等待后续的一些分享~
References
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview?view=aspnetcore-9.0&WT.mc_id=DT-MVP-5004222
https://sparktodo.weihanli.xyz/index.html?urls.primaryName=OpenAPI+V1+Docs
https://sparktodo.weihanli.xyz/scalar/v1
https://github.com/WeihanLi/WeihanLi.Web.Extensions/blob/dev/samples/WeihanLi.Web.Extensions.Samples/Program.cs
https://github.com/WeihanLi/SparkTodo/blob/main/SparkTodo.API/Program.cs
https://github.com/scalar/scalar/
https://github.com/scalar/scalar/blob/main/documentation/integrations/dotnet.md
https://github.com/scalar/scalar/issues/1851
https://github.com/WeihanLi/dotnet-httpie
https://github.com/martincostello/openapi-extensions