ASP.NET Core 8 Swagger UI 入门使用

介绍

Swashbuckle 有三个主要组成部分：

• Swashbuckle.AspNetCore.Swagger：将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。
• Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。
• Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。

Swashbuckle安装

• 选择要添加Swagger UI 的项目
• 右键点击管理NuGet程序包,搜索“Swashbuckle.AspNetCore”
• 找到最新的“Swashbuckle.AspNetCore”包，点击安装即可。

添加并配置 Swagger 中间件

• ​ 将 Swagger 生成器添加到 Program.cs 中的服务集合：

  var builder = WebApplication.CreateBuilder(args);
  
  // Add services to the container.
  
  builder.Services.AddControllers();
  
  //将Swagger 生成器添加到服务集合中
  builder.Services.AddSwaggerGen();
  
  

• 在 Program.cs 中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务：

  var app = builder.Build();
  //仅当前环境设置为“开发”时，上述代码才会添加 Swagger 中间件。 UseSwaggerUI 方法调用会启用 Swagger UI 工具的嵌入版本。
  if (app.Environment.IsDevelopment())
  {
      app.UseSwagger();
      app.UseSwaggerUI();
  }
  

• 启动应用，并导航到 https://localhost:<port>/swagger/v1/swagger.json。 生成的描述终结点的文档显示在 OpenAPI 规范 (openapi.json) 中。

  

• 可在 https://localhost:<port>/swagger 找到 Swagger UI。 通过 Swagger UI 浏览 API，并将其合并其他计划中。

  

要在应用的根 (https://localhost:<port>/) 处提供 Swagger UI，请将 RoutePrefix 属性设置为空字符串：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    options.RoutePrefix = string.Empty;
});