使用 Swagger 工具记录 ASP.NET Core Web API
API 可具有巨大的价值，但除非开发人员知道如何使用它，否则它不会具有吸引力。 开发人员希望尽可能快地集成 API。 好的 API 文档可帮助开发人员了解 API 的功能及其使用方法，从而让集成更高效。
传统上，所有描述 API 及其使用方法的文档都是人工编写的。 现在有了名为 OpenAPI 的标准 API 描述规范。 Swagger UI 为 API 提供 OpenAPI 规范的实现工具和测试工具。 Swashbuckle 是一个开放源代码包，它使用 .NET 反射直接从 Web API 控制器自动生成 OpenAPI 描述文档。 Swashbuckle 有助于实现描述过程自动化，这样团队就可以更轻松地生成、维护和使用基于 OpenAPI 的 API 文档。 你可以描述 API，然后让工具生成丰富的文档。
什么是 OpenAPI？
OpenAPI 是用于描述 REST API 的规范。 它与语言无关，可描述整个 API，包括：
- 可用的终结点
- 操作参数
- 身份验证方法
- 联系信息和其他信息
可在 YAML 或 JSON 中编写 API 规范。 通过使用 OpenAPI 规范，人类和计算机无需访问其源代码即可了解 API 的功能。
什么是 Swagger？
Swagger 是一组围绕 OpenAPI 规范构建的开源工具。 这些工具可以帮助你设计、构建和记录 REST API。 Swagger 使用 API 的 OpenAPI 规范来理解其结构。
例如，Swagger UI 是一种工具，可在浏览器中直观地呈现使用 OpenAPI 规范定义的 API 的文档。 Swagger Codegen 可采用相同的 API OpenAPI 规范并生成客户端 SDK。
什么是 Swashbuckle？
Swashbuckle 是开放源代码 Swagger 实现，用于使用 .NET 反射为 .NET Core API 生成 Swagger 文档。
Swashbuckle 有三个主要组件：
Swashbuckle.AspNetCore.Swagger：该组件是 Swagger 对象模型和中间件，用于将
SwaggerDocument对象公开为 JSON 终结点。Swashbuckle.AspNetCore.SwaggerGen：该库是一个 Swagger 生成器，可直接从路由、控制器和模型构建
SwaggerDocument对象。 代码库通常与 Swagger 终结点中间件结合使用，以自动显示 Swagger JSON。Swashbuckle.AspNetCore.SwaggerUI：此包是 Swagger UI 工具的嵌入式版本。 它解释了 Swagger JSON，以便为描述 Web API 功能构建丰富、可自定义的体验。 它包括针对公共方法的内置测试工具。
Swashbuckle CLI：这是一种 .NET 全局工具，安装后就可以在生成/发布期间生成 OpenAPI 规范。 此模块的末尾提供了 Swashbuckle CLI 的下载链接。
由于这些库已添加到应用中，因此可从最新版本的 API 生成 API 文档并将其可视化。 它们创建实时文档，始终与最新代码同步。