开始之前

文档能解析为 JSON 或 YAML，并不代表接口约定完整。本例故意漏掉路径参数定义，让你先看到错误，再补齐定义并核对预期结果。输入仅在浏览器处理。

边看边操作在 OpenAPI 文档检查与预览 中打开实际工作区
01

准备有缺陷的文档

将下面完整示例粘贴到 OpenAPI 文档检查工具，点击“开始分析”。路径包含 {id}，但没有声明对应参数。

示例
{
  "openapi": "3.0.3",
  "info": {
    "title": "订单查询示例",
    "version": "1.0.0"
  },
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "getOrder",
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
02

定位路径参数提示

预期看到 1 个接口 GET /orders/{id}，以及“缺少路径参数定义”的 error 提示。筛选框输入 /orders 可以聚焦接口；不要把接口成功列出理解为文档已通过全部检查。

03

替换为补齐后的文档

本例将 id 明确声明为 path 参数，并设置 required: true。复制下面完整版本覆盖输入，重新分析。

示例
{
  "openapi": "3.0.3",
  "info": {
    "title": "订单查询示例",
    "version": "1.0.0"
  },
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "getOrder",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
04

核对结果后交付

修正后的示例仍有 1 个 GET 接口、200 响应，本工具不应再报告结构问题。下载结果，并把实际文档版本与接口地址一并交给协作者；示例文档本身不部署接口。

引用报错怎样继续

未找到 #/components/... 时，检查拼写、大小写和被引用对象是否真的存在。外部 URL 引用会被标记为人工复核，不会自动下载；可以用可信构建流程先生成单文件文档，再检查。不要为了消除提示直接删掉真实约束。

经常混淆的两个版本

openapi 表示文档采用的规范版本，info.version 表示你的 API 文档版本。把 info.version 从 1 改为 2 不会自动转换规范，也不会改变接口行为。

规范依据与检查范围

以 OpenAPI 3.0 / 3.1 为输入。工具在浏览器本地执行基础结构检查，不调用实际 API，不自动获取外部引用，也不替代完整规范校验、鉴权测试或消费者契约测试。

要点总结
  • 先修复结构问题，再讨论业务兼容性。
  • 路径占位符必须有对应参数定义。
  • 零提示只代表这组基础规则未发现问题。