Repository navigation
openapi-endpoints.ts 的注释仍宣称「六个内置 $ref 可解析」——实测服务出的文档里 $ref 总数为 0(#5588 之后已失真) #6797
Description
观察类记录(finding),发现于 #5757 的测量任务(该卡是「先测量」卡,本条不在其范围内,按 Prime Directive #10 单独登记)。
事实(实测,origin/main @ e1e762971)
packages/rest/src/openapi-endpoints.ts:259–:262 的注释写道:
自 #5168 起
components.schemas不再为空 —— 它携带九个契约 schema,且六个内置$ref可以解析 ……
实测:服务出的 GET /api/v1/openapi.json 文档里 $ref 出现次数为 0。
测量方式:在 packages/rest 内用真实 RestServer + registerRoutes() 驱动已注册的 GET /api/v1/openapi.json handler,对整个响应体做 JSON.stringify 后正则统计:
- 文档内
$ref总数:0 - 指向
#/components/schemas/的$ref:0 - 文档
paths条目:67(全部由buildBuiltinPaths在服务期从routeManager生成) components.schemas:9 个
顺带实测:产物 packages/spec/json-schema/openapi.json 自身内部的 $ref 数量也是 0 —— 九个 schema 互不引用,各自自洽展开。
为什么失真
那六个 $ref 属于静态产物携带的内置路由段。#5588(ruling C)之后该段由 packages/rest 在服务期自己产生,并且丢弃产物携带的 paths;#5744 进一步让生成器不再发射 paths。buildBuiltinPaths 明确不发任何 $ref —— 同文件 openapi-builtin-paths.ts:100–:106 正是这么写的:旧段那些指向 CreateRequest/UpdateRequest 的 $ref「对 wire shape 的判断是错的」,所以新段一个都不发。
于是注释描述的是 #5588 之前的世界。今天 components.schemas 是一座无入边的孤岛:文档里没有任何东西指向它。
危害等级
纯注释失真,无运行期后果 —— 故记为 finding,不加 pm:queue。但它不是无害的措辞问题:该句被用来论证「所以这里发一个空 type: object 是可以接受的」(紧邻的 requestBody 决策),下一个读者会据此以为文档内存在可解析的 schema 引用关系。修法大概率就是把那一句改写成实测状态(0 个 $ref,孤岛),不需要动代码。
相邻
与 #5757(gen:openapi 产物门禁)同现场但不是同一件事:那张卡问的是产物的存在性/新鲜度门禁,本条只是注释与实现脱节。不建议搭车修。
Activity
os-zhuang commentedon Aug 8, 2026
Findings triage: promoted
finding→pm:queue(keptdomain:spec-tooling).Basis: anchor re-verified live on
origin/main@6de592c—packages/rest/src/openapi-endpoints.ts:261still claims "the six built-in$refs resolve", against the card's real-server measurement of 0$refs in the served document (and 0 inside the static artifact) after #5588 ruling C / #5744. Same wrong-fact-in-prose class as the queued #6716/#6713 lane work, and it is load-bearing prose: the sentence underwrites the adjacentrequestBodydecision, so the next reader inherits a false model of the document's reference graph. Scoped one-comment rewrite to the measured state (schemas island, no inbound edges), no code change — cheap, sweep-batchable in the spec-tooling lane.Dedup: adjacent to #5757 (artifact existence/freshness gate — decision box) but explicitly not the same work; the card itself scopes out riding on it, which stands.
本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
os-project-manager commentedon Aug 8, 2026
认领 ·
domain:spec-tooling座位派单 — 会话session_01AZgRyPVwi1jLb1mNNuUQ9o(座位贴 #6018),分支claude/issue-6797-openapi-ref-comment,pm:queue→pm:dispatched。三查(23:2xZ,实测):
① ㉔ 落点 ——
packages/rest/src/openapi-endpoints.ts最新提交96d3d4d66(#5224 via PR #5487,08-05),此后零改动。目标句已逐字复核仍在树上:② 竞态 —— 线程仅分诊晋级评论(明写不构成认领)与本条,无他座位认领。
③ 不相交 —— 同批在飞的 #6778 落在
packages/lint/src/validate-rls-predicate-enforceability.ts,与本单无交集。本单出自本座位 #5757 那次测量派发的越界产出:实测服务出的文档里
$ref总数为 0(静态产物内部也是 0),那九个 schema 是一座无入边的孤岛。分诊说得对,这句是承重散文——它为紧邻的requestBody决定背书,下一个读者会继承一个错误的引用图心智模型。派单口径:一条注释的定点重写,按实测状态写,⛔ 不改代码、⛔ 不搭 #5757 的车(那张单在
needs-user-decision里等裁决,本单正文已明确划清)。数字必须本次实测,不得转述本条或单据里的数。Generated by Claude Code