Web API 项目中启用 Swagger UI

Swashbuckle 和 ASP.NET Core 入门

Swagger UI 提供了基于 Web 的 UI，它使用生成的 OpenAPI 规范提供有关服务的信息。 Swashbuckle 和 NSwag 均包含 Swagger UI 的嵌入式版本，因此可使用中间件注册调用将该嵌入式版本托管在 ASP.NET Core 应用中。 Web UI 如下所示：

控制器中的每个公共操作方法都可以从 UI 中进行测试。 选择方法名称可以展开该部分。 添加所有必要的参数，然后选择“试试看!”。

一、WebAPI 项目中添加 SwaggerUI

从“管理 NuGet 程序包”对话框中：

• 在搜索框中输入“Swashbuckle.AspNetCore”

Swashbuckle 有三个主要组件(分别引用以下三个组件)：

• Swashbuckle.AspNetCore.Swagger：将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。

• Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。

• Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。

二、添加并配置 Swagger 中间件

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

// Add services to the container.

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

//SwaggerGen 将生成器添加到服务集合
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",new Microsoft.OpenApi.Models.OpenApiInfo { Title ="Swagger项目",Version ="v1"});
});

var app = builder.Build();

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

if (app.Environment.IsDevelopment())
{
    app.UseWebAssemblyDebugging();
    app.UseSwagger();//启用中间件为生成的 JSON 文档和 Swagger UI 提供服务
    app.UseSwaggerUI();//启用中间件为生成的 JSON 文档和 Swagger UI 提供服务
}
else
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

仅当将当前环境设置为“开发”时，上述代码才会添加 Swagger 中间件。 UseSwaggerUI 方法调用启用了静态文件中间件。

启动应用,可在 https://localhost:<port>/swagger 找到 Swagger UI。 通过 Swagger UI 浏览 API

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