什么是 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 编辑器 – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 定义。
  • Swagger UI – 将 OpenAPI 定义渲染为交互式文档。
  • Swagger Codegen – 从 OpenAPI 定义生成服务器存根和客户端库。
  • Swagger 编辑器下一代 (beta) – 基于浏览器的编辑器，您可以在其中编写和审阅 OpenAPI 和 AsyncAPI 定义。
  • Swagger Core – 用于创建、使用和处理 OpenAPI 定义的 Java 相关库。
  • Swagger 解析器 – 用于解析 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 集成的 开源 和 商业工具。