练习 - 使用 Swashbuckle 创建 OpenAPI 文档

8 分钟

此练习将向 ASP.NET Core Web API 应用程序添加 Swagger 和 Swagger UI。 Swagger 工具有助于创建用于描述 Web API 的 OpenAPI 文档。

注意

将源代码下载到本地计算机以完成此练习。下载文件后，需要解压缩该文件。

下载：ASP.NET Core Web API 应用程序。

选择“下载原始文件”按钮。

解压缩 exercise.zip 文件。

添加 Swagger 工具

打开 Visual Studio 并找到 ASP.NET Core Web API 应用。
在“解决方案资源管理器”中，右键单击项目，然后选择“管理 NuGet 包”菜单。
在“NuGet 包管理器”中，搜索 Swashbuckle.AspNetCore。选择该包并安装。

现在已安装 NuGet 包。关闭“NuGet 包管理器”选项卡。

配置 Swashbuckle 以生成 OpenAPI 文档

打开 Startup.cs 文件。

在 namespace InventoryManagement.ApiApp 这一行的正上方添加以下指令。

/* === using directive BEGIN === */
using Microsoft.OpenApi.Models;
/* === using directive END === */

将 ConfigureServices(IServiceCollection) 方法内的所有代码替换为以下代码：

    services.AddControllers();

    /* === SwaggerGen BEGIN === */
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Inventory Management", Version = "v1" });
    });
    /* === SwaggerGen END === */

在 Configure(IApplicationBuilder, IWebHostEnvironment) 方法中，找到 if (env.IsDevelopment()) 条件语句，并将该语句上面的所有内容替换为以下代码：

    /* === SwaggerUI BEGIN === */
    app.UseSwagger(c =>
    {
        c.PreSerializeFilters.Add((swagger, httpReq) => {
            var server = new OpenApiServer() { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" };
            swagger.Servers = new List<OpenApiServer>() { server };
        });
    });
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "InventoryManagement.ApiApp v1"));
    /* === SwaggerUI END === */

注意

应仅在开发环境中启用 Swagger 终结点，这一点非常重要。否则，它可能会向公众公开 API。

现在，你已完成为 ASP.NET Core Web API 应用激活 OpenAPI 文档功能。保存 Startup.cs 文件。更改应如下面的屏幕截图所示。

修改的文件：Startup.cs

生成 OpenAPI 文档文件

选择 Visual Studio 顶部中间的“调试”按钮。

它会自动打开 web 浏览器并显示 Swagger UI 页面。

你可能会看到 404 错误页。在这种情况下，请在浏览器的地址栏中输入 URL https://localhost:<port_number>/swagger。例如，在下面的屏幕截图中，URL 为 https://localhost:44371/swagger。
选择此链接可打开 OpenAPI 文档页面。
OpenAPI 文档是动态呈现的。

练习 - 使用 Swashbuckle 创建 OpenAPI 文档

添加 Swagger 工具

配置 Swashbuckle 以生成 OpenAPI 文档

生成 OpenAPI 文档文件

反馈