使用 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 UI.

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

OpenAPI Document.

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