带有 Swagger/OpenAPI 的 ASP.NET Core Web API 帮助页ASP.NET Core web API help pages with Swagger / OpenAPI

使用 Web API 时，了解其各种方法对开发人员来说可能是一项挑战。 也称为OpenAPI，解决了为 Web API 生成有用文档和帮助页的问题。它具有诸如交互式文档、客户端 SDK 生成和 API 可发现性等优点。

本文展示了 和 NSwag .NET Swagger 实现：

Swagger 是一个与语言无关的规范，用于描述 API。Swagger 项目已捐赠给 OpenAPI 计划，现在它被称为开放 API。这两个名称可互换使用，但 OpenAPI 是首选。它允许计算机和人员了解服务的功能，而无需直接访问实现（源代码、网络访问、文档）。其中一个目标是尽量减少连接取消关联的服务所需的工作量。另一个目标是减少准确记录服务所需的时间。

Swagger 流的核心是 Swagger 规范，默认情况下是名为 swagger.json 的文档 。它由 Swagger 工具链（或其第三方实现）根据你的服务生成。它描述了 API 的功能以及使用 HTTP 对其进行访问的方式。它驱动 Swagger UI，并由工具链用来启用发现和客户端代码生成。下面是为简洁起见而缩减的 Swagger 规范的示例：

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

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

备注