OpenAPI 3中/shops/{shopId}/pets下两个路径是否存在匹配歧义？

核心结论 #

这组路径不存在规范明确禁止的非法定义场景，也不属于跨结构交叉匹配的强歧义，仅符合规范里“边界场景由工具自行决定解析规则”的弱覆盖范畴，实际日常使用完全不会产生解析混淆。

逐条对应规范的判定逻辑 #

之前对照规范感觉匹配不上三类情形，本质是对规则的适用边界理解有偏差，把三个规则的触发条件拆清楚就一目了然：

• 关于“concrete（非模板）路径优先级高于模板路径”的规则
  你之前误把/shops/{shopId}/pets/_search当成了全模板路径，实际上这个路径的最后一段是写死的固定值_search，属于标准的concrete路径段，和同前缀下最后一段是模板{petId}的路径，结构上完全匹配规范举的/pets/mine与/pets/{petId}的示例：当访问对应路径时，固定值的_search段会优先匹配，不存在二选一的强制冲突。
• 关于“同层级模板命名不同属于非法相同路径”的规则
  这条规则的触发前提非常严格：两个路径在完全相同的分段位置，都是大括号包裹的模板参数，只是参数名存在差异——比如/pets/{petId}和/pets/{name}，最后一段都是模板，只是一个叫petId、一个叫name，这种才会被判定为非法的重复定义。
  你对比的两个路径里，/shops/{shopId}/pets/_search的最后一段根本不是模板，完全不满足这条规则的触发条件，自然不会被判定为非法。
• 关于“交叉结构的歧义解析”的规则
  这类歧义指的是两个路径的分段结构从根节点开始就不对齐，比如规范示例里的/{entity}/me是两段结构、第二段为固定值，/books/{id}是两段结构、第一段为固定值，碰到/books/me这类请求时两个路径会同时命中，才属于跨结构的强歧义。
  你对比的两个路径从根到pets段的结构完全一致：都是/shops/[shopId模板段]/pets/[最后一段]，根本不存在结构交叉，自然不触发这类歧义判定。

之前判定偏差的来源 #

你之前会觉得两个路径对不上三类情形，核心是下意识把/shops/{shopId}/pets/_search归类成了模板路径，忽略了路径段的属性判定只看语法形态：

• 只要某一段是没有大括号包裹的固定字符串，这一段就是concrete段
• 只要某一段是大括号包裹的参数，才是模板段

两个路径的共同前缀完全对齐，只是最后一段一个是固定值_search、一个是模板参数，这种结构的匹配优先级是规范明确约定好的：固定值段优先于模板段。哪怕业务上允许把_search作为petId的合法取值，这也是业务设计的问题，不是OpenAPI路径定义本身的语法歧义。

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