swagger - 什么是 Swagger、Swashbuckle 和 Swashbuckle UI

Question

这是我的理解:

• Swagger 是一种编写文档的符号/规则。但为什么它被称为框架(如 Angular/MVC)？
• Swashbuckle 是一个生成文档(基于 Swagger 规则)的程序(JavaScript？)。
• Swagger UI 显示文档。它使用 Swashbuckle 来做到这一点。

此信息正确吗？如果没有，有人可以简单地解释一下 Swagger、Swashbuckle 和 Swashbuckle UI 的含义吗？

此外，如果我不使用它，作为 API 开发人员我会失去什么？

Answer 1

Swagger is a notation/rules to write documentation. But why is it called a framework(Like angular/MVC)?

它可能被称为“框架”，因为它的目的是提供一种系统的方法来标记 OpenAPI 规范下的任何 RESTful 服务的接口(interface)。这对开发人员来说是一件大事，因为该规范由信誉良好的 Linux 基金会下的开放 API 计划 (Open API Initiative) 监督。

Swashbuckle is a program(javascript ?) that generates the documentation(based on Swagger rules)

Swashbuckle 更像是一个可以在 .NET Web API 项目中使用的包(或库)。正如您所正确指出的，它的目的是为您的项目生成 Swagger 规范。此外，Swagger UI 包含在 Swashbuckle 中，因此如果您在 .NET 中开发 API，它确实是一个很好的一站式软件包。它几乎完全是用 C# 编写的，而不是 JavaScript。

Swagger UI displays the documentation. It uses Swashbuckle to do this.

是的，它确实以一种友好的、人性化的方式显示了 Swagger 规范。然而，Swashbuckle 并不是必需的组件。除了我之前所说的之外，它们是完全互斥的。

Also what do I lose as an API developer, if I do not use this.

这现在已经进入了舆论领域，但我会尽力客观地对待它。我使用 Swashbuckle 协助为我的应用程序 API 创建客户端。在完成了实现学习曲线(并不多)之后，这个包为我节省了很多自己编写客户端的时间。对于小型应用程序来说，编写 Web 客户端是一件微不足道的事情，但企业级应用程序的复杂性往往会不断增长和/或变化，因此最好能够完全自动化地创建/更新这些客户端。

简而言之，如果您决定不使用它，则必须采用 API 客户端生成的替代方法或自己编写/更新客户端。如果您只开发后端，这对您来说可能完全没有意义，但它肯定会对负责创建将使用您的 API 服务的客户端应用程序的人有所帮助。

希望这些答案对您有所帮助。干杯!