入门

目标受众

本指南面向希望从将 API 正式化到 **OpenAPI 描述** (**OAD**) 中获益的 **基于 HTTP 的 API** 设计师和编写者。

如今，机器可读的 API 描述无处不在，**OpenAPI** 是 **描述新 API 的最广泛采用的行业标准**。因此，值得从一开始就学习它并将其做好。

这些页面是 **OpenAPI 规范** (OAS) 的补充，帮助读者学习它并回答诸如“完成… 的最佳方法是什么？”或“…” 的目的何在？”这些问题自然超出了规范的范围。

• 如果您不确定本指南是否适合您，请阅读下面的下一节。
• 如果您不知道“API”、“机器可读描述”或“OpenAPI”的含义，请从阅读 介绍 章节开始。
• 如果您是第一次编写 **OpenAPI 描述**，请阅读 OpenAPI 规范详解 章节以获取分步教程。
• 如果您已经拥有 **OpenAPI** 经验，但需要有关特定主题的帮助，请查看 OpenAPI 规范详解 章节的索引；它还包含高级主题。
• 最后，请确保您了解推荐的 最佳实践，以充分利用 **OpenAPI**！
• 当然，您始终可以参考实际的 OpenAPI 规范 以供参考。

使用 OpenAPI 的优势

将您的 API 正式描述在机器可读的格式中，可以让自动化工具处理它，从而立即打开通往以下领域的大门

• **描述验证和代码整理**：检查您的描述文件在语法上是否正确，是否符合规范的特定版本以及团队的其他格式指南。
• **数据验证**：检查通过 API 流动的数据（双向）在开发过程中以及部署后是否正确。
• **文档生成**：根据机器可读的描述创建传统的供人阅读的文档，该文档始终保持最新。
• **代码生成**：创建任何编程语言中的服务器和客户端代码，使开发人员不必执行数据验证或编写 SDK 胶水代码，例如。
• **图形编辑器**：允许使用 GUI 轻松创建描述文件，而不是手动键入。
• **模拟服务器**：创建提供示例响应的伪服务器，您和您的客户可以在编写任何代码之前开始对其进行测试。
• **安全分析**：在 API 设计阶段发现可能的漏洞，而不是在更晚的时候发现。

除此之外，**OpenAPI 规范**还为您提供

• **非专有格式**：您可以在规范的未来方向上有发言权！
• **最发达的工具生态系统**：作为先前陈述的直接结果，OpenAPI 提供了大量工具来处理它。只需快速浏览一下 OpenAPI 工具。
• **机器和人类都可以读取的格式**：即使手动编写 OAD 不是最方便的方式（参见 最佳实践），它们也是可以轻松浏览的纯文本文件，以防需要调试。

因此，从本页顶部的列表中选择您想要的入口点，开始您的旅程！