Postman校验OpenAPI3格式API提示请求不匹配schema如何解决

这个报错在删光所有新增endpoint仍复现、甚至波及未修改历史接口的情况，问题100%出在全局配置/Postman自身缓存bug，和单个接口逻辑无关，按以下顺序排查即可：

• 先排除YAML全局结构错误
  不要依赖Postman内置校验器，用独立的OpenAPI lint工具（比如@stoplight/spectral）对全量YAML做校验，重点排查三类问题：
  1. 缩进错位：检查components、servers、security这些根级块有没有缩进错误，比如本该属于components.schemas的结构意外跑到和paths同级的根节点，会直接触发全局schema校验失败
  2. 重复定义：检查有没有重名的schema ID、全局参数、安全策略，复制旧接口内容时很容易带重复声明，Postman对重复定义的容错极差，会把所有关联接口全标记为不匹配
  3. 格式简写错误：开头的版本声明必须写全版本号，比如openapi: 3.0.3，不能写openapi: 3这类简写；servers块必须填合法的url字段，带变量的要给默认值，这类全局字段格式错了会直接导致所有接口校验失败，和你写没写endpoint无关
• 清理Postman损坏的校验缓存（对应反复弹黄条、确认变更仍报错的问题）
  这是Postman存在多年的已知同步bug，旧Collection的错误标记会存在云端/本地缓存里清不掉，按以下操作处理：
  1. 先把当前API的YAML定义全量导出到本地备份
  2. 打开出问题的Collection设置，临时勾选Disable schema validation后保存
  3. 完全退出Postman，清空对应系统下的Postman缓存目录：
     • Windows：%APPDATA%\Postman\Cache
     • Mac：~/Library/Application Support/Postman/Cache
     • Linux：~/.config/Postman/Cache
  4. 重启Postman后新建空白Collection，把本地备份的YAML重新导入新Collection即可，不要在原Collection上继续修改，原Collection的错误标记无法通过普通编辑清除
• 排查隐式全局必填项
  检查全局parameters、securitySchemes块里有没有新增的必填请求头、query参数、鉴权字段，如果全局加了必填项但没有同步更新所有接口（包括历史老接口）的请求示例，Postman会因为示例请求缺必填字段，把所有接口都标成请求不匹配schema，哪怕你从来没改过老接口的单独配置。

快速验证方法：新建一个最简的合法OpenAPI3定义，只保留版本声明、一个空server、一个无参数无请求体的GET测试接口，导入后如果校验正常，就顺着上面三个点查原文件的问题即可。

内容的提问来源于stack exchange，提问作者m0r