openapi3.0

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

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

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

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

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

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

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

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

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