OpenAPI

OpenAPI 规范是一种用于描述 HTTP API 的标准格式，以便工具（而不仅仅是人）能够读取它。一份文档列出了所有路径和方法、它们各自接受的参数、以 JSON Schema 形式表示的请求和响应主体、状态码以及身份验证方案。它最初名为 Swagger；OpenAPI 3.1 是当前的主要版本。

工作原理

工具可以从一份文档生成交互式参考文档、多种语言的客户端 SDK、服务器存根、模拟服务器和契约测试。同一份文件可以在持续集成 (CI) 系统中与正在运行的 API 进行比对，从而确保描述与实现不会出现偏差，否则构建就会失败。

误解

OpenAPI 文件证明 API 的行为符合描述。这是一种声明，而非测试：没有任何规定阻止处理程序返回规范中从未提及的字段或从未列出的状态。它的价值在于通过与实际响应进行比对，而这正是契约测试的作用。

点击这里试试

这里的每个 API 都会在/docs/{api-id}/openapi.json发布自己的 OpenAPI 3.1 文档，而/openapi.json涵盖了整个目录；两者都由文档页面呈现的相同定义生成。

相关内容

• 合同测试
• JSON 模式

资料来源

• OpenAPI 3.1 specification

其他术语

• 合同测试 — 测试 API 及其使用者是否在请求和响应的形式上达成一致，而无需同时运行它们。
• JSON 模式 — 用于描述有效 JSON 文档外观的 JSON 词汇表，以便可以自动验证文档。
• REST API — 将系统建模为可寻址资源的 API，可通过标准 HTTP 方法进行操作。
• API 端点 — 一个 URL 加上一个 HTTP 方法——客户端可以调用的最小 API 单元。
• 查询参数 — URL 中问号后面的键值对，用于过滤、排序、分页或调整端点返回的内容。
• 路径参数 — URL 路径中的可变部分，例如/orders/42中的 42，用于标识一个特定的资源。

阅读英文版

所有术语 · 测试技巧 · 全部 39 个模拟 REST API

最后更新时间 2026年10月16日