在本系列博客文章中，我们将帮助您深入了解 Swagger，了解它的全部内容以及如何使用它将您的 API 提升到一个新的水平。每篇文章将涵盖这些方面之一。
让我们来谈谈问题：我们有一个想要记录的 API。具体来说，一个 REST API（我们稍后会介绍“REST”的含义）。
我们可以维护一个包含该信息的文档或 HTML 网站，甚至可以使用某些工具从我们的代码生成它。这种方法的缺点是我们需要手动（或通过半自动过程）维护它，而且虽然它是人类可读的，但它并不是真正的机器可读的。
另一种方法是使用 WADL，它可以通过某些工具生成。在这种情况下，它是机器可读的，但绝对不是人类可读的。此外，手动编写 WADL 是一个繁琐的过程。
为了寻求更简单的解决方案，Swagger 应运而生。Swagger 是一组规则（换句话说，一种规范），用于描述 REST API 的格式。该格式既是机器可读的又是人类可读的。因此，它可以用于在产品经理、测试人员和开发人员之间共享文档，也可以被各种工具用来自动化 API 相关流程。
当我们说 REST 时，我们不一定遵守 RESTful 规则。我们指的是 REST API 背后的基本概念。虽然 WADL 以复杂性为代价涵盖了几乎所有可能的 API 设计，但 Swagger 的目标是涵盖更常见的设计模式，同时更易于编写和使用。
在我们最新的迭代版本 Swagger 2.0 中，我们使该格式在 JSON 和 YAML 中都可接受，以便更易于编辑。
为了帮助您了解 Swagger 的外观，请查看以下示例
swagger: "2.0"
信息
版本: "1.0"
标题: "Hello World API"
路径
/hello/{user}
get
描述：返回对用户的问候！
参数
- 名称: user
位于: path
类型: string
必需: true
描述：要问候的用户的姓名。
响应
200
描述：返回问候语。
模式
类型: string
400:
描述：提供了“user”中的无效字符。
在上面的示例中，我们描述了一个简单的“Hello World API”。它公开了一个 URL - “/hello/{user}”。“user”是 API 的单个参数，定义为路径的一部分，我们说它是一个字符串。我们还描述了成功的响应，并提到它也是一个字符串。如果“user”包含无效字符，则可能会收到一个通用的 400 错误。您还可以看到在整个操作过程中，我们提供了额外的文档。
差不多就是这样了 - 这就是 Swagger 的精髓。每个人都可以在 https://swagger.org.cn/specification 阅读 Swagger 规范或阅读此 Swagger 教程。它包含有关如何定义路径、参数、响应、模型、安全性等信息。Swagger 规范本身是开源的，并根据 ASL 2.0 许可提供。
在接下来的博客文章中，我们将介绍如何在您的项目中开始使用 Swagger，它如何适应一般的 API 生命周期以及现有的开源和商业工具。
如果您希望我们在此系列中介绍关于Swagger 入门的任何特定方面，请随时与我们联系并提出请求 - 我们将尽力提供相关信息。