什么是 OpenAPI？

OpenAPI 规范（原 Swagger 规范）是一种用于 REST API 的 API 描述格式。OpenAPI 文件允许您描述整个 API，包括：

• 可用端点（/users）和每个端点上的操作（GET /users、POST /users）
• 每个操作的参数输入和输出
• 认证方法
• 联系信息、许可、使用条款和其他信息。

API 规范可以用 YAML 或 JSON 编写。该格式易于学习，对人类和机器都可读。完整的 OpenAPI 规范可在 GitHub 上找到：OpenAPI 3.0 规范

什么是 Swagger？

Swagger 是一套围绕 OpenAPI 规范构建的开源工具，可以帮助您设计、构建、文档化和使用 REST API。主要的 Swagger 工具包括：

• Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 定义。
• Swagger UI – 将 OpenAPI 定义呈现为交互式文档。
• Swagger Codegen – 从 OpenAPI 定义生成服务器存根和客户端库。
• Swagger Editor Next (beta) – 基于浏览器的编辑器，您可以在其中编写和审查 OpenAPI 和 AsyncAPI 定义。
• Swagger Core – 用于创建、使用和处理 OpenAPI 定义的 Java 相关库。
• Swagger Parser – 用于解析 OpenAPI 定义的独立库。
• Swagger APIDom – 提供一个统一的结构，用于描述各种描述语言和序列化格式的 API。

为什么要使用 OpenAPI？

API 描述自身结构的能力是 OpenAPI 所有出色特性的根源。一旦编写完成，OpenAPI 规范和 Swagger 工具可以通过多种方式进一步推动您的 API 开发：

• 设计优先用户：使用 Swagger Codegen 为您的 API 生成服务器存根。剩下的唯一事情就是实现服务器逻辑——您的 API 就可以上线了！
• 使用 Swagger Codegen 为您的 API 生成超过 40 种语言的客户端库。
• 使用 Swagger UI 生成交互式 API 文档，让您的用户可以直接在浏览器中尝试 API 调用。
• 使用规范将 API 相关工具连接到您的 API。例如，将规范导入 SoapUI 以创建 API 的自动化测试。
• 还有更多！查看与 Swagger 集成的开源和商业工具。