什么是 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 集成的开源和商业工具。