体验 dotnet 9 中的 OpenAPI 支持

摘要：openapi生成了 OpenAPI 文档之后，我们可以借助 Swagger UI 框架来根据 openapi 文档来显式 OpenAPI 调试界面，我们可以使用原有的 UI 框架，指定好新的路径即可

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生成了 OpenAPI 文档之后，我们可以借助 Swagger UI 框架来根据 openapi 文档来显式 OpenAPI 调试界面，我们可以使用原有的 UI 框架，指定好新的路径即可

比如说我们使用原来的 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 文档自定义的支持有所不同

Swashbuckle Swagger UI

在 dotnetconf 2024 的 session 分享上，展示了另外一个 swagger UI 的选项 -- scalar

在 dotnet 9 还没正式发布的时候有注意到 OpenAPI 功能主要开发贡献的 Safia就有向这个项目贡献 dotnet 的支持

我们来看下集成 scalar ui，首先添加Scalar.AspNetCoreNuGet 包引用，在原来集成 OpenApi 的基础上，需要添加对 scalar endpoint 的注册var builder = WebApplication.CreateSlimBuilder(args);
//
builder.Services.AddOpenApi;

var app = builder.Build;

//
app.MapOpenApi;
app.MapScalarApiReference;

//...
注册好之后允许访问/scalar/v1

scalar-ui

另外一个 API 的 ui 效果如下

scalar-ui2注意截图的话可以看到，这个默认请求示例是 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

来源：opendotnet