ASP.NET Core（三十六）使用 Scalar 替代 Swagger 显示 API 文档

小渣渣

需求：Scalar 比较强大，能够在 API 文档自动生成不同语言的 Http 调用代码，使用 Scalar 替代 Swagger 显示 API 文档。

在.NET 9发布以后ASP.NET Core官方团队发布公告已经将Swashbuckle.AspNetCore（一个为ASP.NET Core API提供Swagger工具的项目）从ASP.NET Core Web API模板中移除，这意味着以后我们创建Web API项目的时候不会再自动生成Swagger API文档了。那么今天咱们一起来试试把我们的EasySQLite .NET 9的项目使用Scalar用于交互式API文档。

链接：超链接登录可见。

Swagger被移除的原因可以总结为以下几点：

• Swashbuckle 维护不力：Swashbuckle 项目不再由社区所有者积极维护，存在许多问题未得到解决，并且未发布兼容 .NET 8 的正式版本。
• 转向 Microsoft.AspNetCore.OpenApi：ASP.NET Core 团队将增强 Microsoft.AspNetCore.OpenApi 的功能，以取代 Swashbuckle 并实现 OpenAPI 文档生成。
• 已有替代方案：除了 Swashbuckle，还有 NSwag 等其他项目支持 OpenAPI 文档生成和客户端/服务器代码生成，开发者可以根据项目需求选择合适的方案。
• 增强内置 API 支持：从 ASP.NET Core 3.1 开始，框架已经提供了 ApiExplorer 等元数据支持，结合 Visual Studio 和 Visual Studio Code 对 .http 文件的内置支持，API 测试和调试体验更佳。
• 推动 OpenAPI 成为核心组件：ASP.NET Core 团队计划在 .NET 9 中进一步提升 OpenAPI 的集成度，将其作为核心组件，专注于生成 JSON 格式的 OpenAPI 文档。
  

Scalar

Scalar是一个功能强大、易于使用的API客户端和文档生成工具，适用于各种规模的API项目，支持多种编程语言和平台。

开源地址：超链接登录可见。

ASP.NET Core 集成 Scalar

集成文档：超链接登录可见。

新建一个 ASP.NET Core 9 项目，引用如下：

登录可见。

在 Program.cs 添加服务和 scalar 中间件，代码如下：

登录可见。

编辑 WeatherForecastController.cs 控制器，代码如下：

登录可见。

启动项目，打开浏览器访问：http://localhost:5088/api-docs，如下图：



可以选择为不同语言的 Http 库生成具体的调用代码，以 C# HttpClient 库为例，生成的代码如下：



也支持在线接口测试，点击 Test Request 按钮，填写 post 的数据，然后点击 send 发送请求，如下图：



自定义默认的 HTTP 客户端，对于 C# 团队，我们希望打开 API 文档界面，自动显示的是 C# HttpClient 调用代码，不想第一次都手动选择，配置如下：

登录可见。

删除询问 AI 功能，去掉 Ask AI Agent 按钮，感觉此功能有点多余，代码如下：

登录可见。

如下图：



删除之后如下图：



禁用 Mcp 功能同理，代码如下：

登录可见。

完整配置如下：

登录可见。

添加 JWT 认证，请求头携带 Bearer Token

向整个 OpenAPI 文档添加安全要求，代码如下：

登录可见。

如下图：



OpenID Connect (OIDC)：超链接登录可见。

参考：

超链接登录可见。
超链接登录可见。

小渣渣

参考博客园文章

超链接登录可见。
超链接登录可见。

其他

超链接登录可见。