在这一系列博客文章中，我们将帮助您深入了解 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"
info
版本: "1.0"
标题: "Hello World API"
paths
/hello/{user}
get
描述: 返回对用户的问候！
参数
- 名称: user
位于: 路径
类型: string
必需: true
描述: 要问候的用户名。
响应
200
描述: 返回问候语。
模式
类型: string
400:
描述: “user”中提供了无效字符。
在上面的示例中，我们描述了一个简单的“Hello World API”。它暴露了一个单独的 URL - “/hello/{user}”。“user”是 API 的唯一参数，定义为路径的一部分，我们说它是一个字符串。我们还描述了成功的响应，并提到它也是一个字符串。如果“user”包含无效字符，可能会收到通用的 400 错误。 您还可以看到，在整个操作过程中，我们提供了额外的文档。
差不多就是这样——这就是 Swagger 的概括。Swagger 规范可在 https://swagger.org.cn/specification 供所有人阅读，或阅读本篇 Swagger 教程。它包括有关如何定义路径、参数、响应、模型、安全性等的信息。Swagger 规范本身是开源的，并根据 ASL 2.0 提供。
在接下来的博客文章中，我们将介绍如何在您的项目中开始使用 Swagger，它如何融入一般的 API 生命周期，以及目前可用的开源和商业工具。
如果您希望我们在此系列中涵盖《Swagger 入门》的任何特定方面，请随时联系我们并提出请求——我们将尽力提供相关信息。