跳到内容

什么是 OpenAPI?

OpenAPI 规范(原 Swagger 规范)是一种用于 REST API 的 API 描述格式。OpenAPI 文件允许您描述整个 API,包括:

  • 可用端点(/users)和每个端点上的操作(GET /usersPOST /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 集成的开源商业工具
© . All rights reserved.