.NET 9 增强 OpenAPI 规范，不再内置swagger

在 .NET 9 的更新中，微软增强了原生 OpenAPI。这一变化表明 .NET 正在更加拥抱开放标准，同时让开发者体验更加轻松高效。本文将探讨为何进行这一更改、OpenAPI 的优势，以及如何在 .NET 9 中使用 OpenAPI。
为什么不再内置 Swagger？

1. 标准化的需求

Swagger 是 OpenAPI 规范的早期实现，固然功能强盛，但它渐渐被视为工具集的一部门，而非行业标准。转向原生 OpenAPI 支持意味着 .NET 正式采用更具广泛认可的标准，从而提拔与其他生态工具的兼容性。
2. 简化依赖关系

移除对 Swagger-specific 组件的依赖，使框架更简便并低落复杂性。开发者可以直接依赖 OpenAPI 规范，而不是被局限在 Swagger 工具集内。
3. 机动性与互操作性

OpenAPI 作为开放标准，被广泛支持于各类工具和平台（如 Postman、API 网关、自动化测试工具等）。这使得 .NET 应用程序更容易集成到多样化的技能栈中。
如何在 .NET 9 中使用 OpenAPI？

.NET 9 提供了对 OpenAPI 的原生支持，通过简单的配置即可天生 OpenAPI 文档并集成可视化工具，如 Swagger UI 和 Scalar API Reference。
以下是配置步骤：
1. 添加必要的服务

在 Program.cs 文件中，调用 AddOpenApi 方法注册 OpenAPI 支持。
2. 映射 OpenAPI 文档

使用 MapOpenApi 映射 OpenAPI 文档路径，便于开发和测试。
3. 集成可视化工具

通过 UseSwaggerUI 或 MapScalarApiReference 添加交互式文档界面。

• UseSwaggerUI 必要安装 Swashbuckle.AspNetCore.SwaggerUi 包。
  1. dotnet add package Swashbuckle.AspNetCore.SwaggerUi

  复制代码

• MapScalarApiReference 必要安装 Scalar.AspNetCore 包。
  1. dotnet add package Scalar.AspNetCore

  复制代码

示例代码

以下代码展示了如何在 .NET 9 中配置和使用 OpenAPI：

1. using Scalar.AspNetCore;
3. namespace WebApplication2
4. {
5.     public class Program
6.     {
7.         public static void Main(string[] args)
8.         {
9.             var builder = WebApplication.CreateBuilder(args);
11.             // 注册控制器和 OpenAPI 服务
12.             builder.Services.AddControllers();
13.             builder.Services.AddOpenApi();
15.             var app = builder.Build();
17.             // 开发环境中启用 OpenAPI 文档和可视化工具
18.             if (app.Environment.IsDevelopment())
19.             {
20.                 app.MapOpenApi(); // 映射 OpenAPI 文档路径
21.                 app.UseSwaggerUI(options =>
22.                 {
23.                     options.SwaggerEndpoint("/openapi/v1.json", "v1"); // 设置文档路径
24.                 });
25.                 app.MapScalarApiReference(); // 映射其他参考路径
26.             }
28.             app.UseAuthorization();
30.             // 映射控制器
31.             app.MapControllers();
33.             app.Run();
34.         }
35.     }
36. }

复制代码

示例解析

• 服务注册
  1. builder.Services.AddOpenApi();

  复制代码
  此行代码启用了 OpenAPI 支持。
  
• 映射文档
  1. app.MapOpenApi();

  复制代码
  这将 OpenAPI 文档映射到默认路径 /openapi/v1.json。
  
• 增加文档可视化
  1. app.UseSwaggerUI(options =>
  2. {
  3.    options.SwaggerEndpoint("/openapi/v1.json", "v1");
  4. });
  5. app.MapScalarApiReference();  

  复制代码
  这将增加swagger和scalar两种可视化工具。
  
• 访问可视化工具
  
  
  
  • SwaggerUI 必要访问/swagger。
    
    
    
  • Scalar 必要访问/scalar/v1。
    
    
    
  这两个工具都可以用于可视化 OpenAPI 文档，提供交互式界面以测试 API。
  
  

总结

.NET 9 中移除内置 Swagger，增加 OpenAPI 支持，是一个符合行业趋势的重要改进。这一变化不仅提拔了开发体验，也使得 .NET 应用能够更高效地与其他工具和平台协作。
通过 OpenAPI 的原生支持和机动的可视化工具选择，开发者可以更轻松地天生文档、测试接口和集成服务。使用示例代码，立即开始在 .NET 9 中体验 OpenAPI 的强盛功能吧！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。