使用 Swashbuckle 创建 OpenAPI 文档

  • 3 分钟

Web API 应具有 OpenAPI 说明文档，才能通过 Visual Studio 发布到 Azure API 管理。

API 管理使用 OpenAPI 文档来发现 Web API 的终结点。 使用 Swashbuckle 工具，VanArsdel 开发人员可以更轻松地为其 Web API 创建 OpenAPI 说明。

OpenAPI 及其功能介绍

OpenAPI 文档为 Web API 定义了一个标准的、与编程语言无关的接口描述。 它可以使人类和计算机在不访问源代码、额外文档或检查网络流量的情况下发现并理解服务的功能。

OpenAPI 图像的屏幕截图。

OpenAPI 文档是用于 Web API 的协定。 这也是使用方应用程序理解并与 Web API 通信所需的全部内容，不必知道 API 位于何处，也不必知晓它们是否正在运行。

从 ASP.NET Core Web API 应用程序生成 OpenAPI 文档

可通过多种方式从 ASP.NET Core Web API 应用生成 OpenAPI 文档。 Swashbuckle 是最常用的方法。

Swashbuckle 程序下载的屏幕截图。

它使用起来很容易，一旦安装到应用上之后便会自动显示 Swagger UI 屏幕。

包含清单管理的 Swagger 用户界面的屏幕截图。

Swashbuckle 还可动态生成 OpenAPI 文档，其中包括所有 API 终结点详细信息、有效负载结构、安全要求等。下面是 VanArsdel 提供的库存管理 Web API 的示例文档。

OpenAPI 文档代码的屏幕截图。

下一单元的练习将介绍如何为 ASP.NET Core Web API 应用启用此 OpenAPI 功能。