[finding] 裁定 C 落地后,服务出的 openapi 文档里 `components.schemas` 无人引用 —— CRUD body 从具体契约退成泛 `{type:'object'}`

[qq9340100]

观察类发现,在 #5744(#5588 裁定 C 第二棒,PR #5967)实施过程中量到。不在该单范围内(落点是 packages/rest,第一棒 #5821 已收官),也不建议顺手改 —— 记下来交分诊。

事实

裁定 C 之后,GET {apiPath}/openapi.json 的 built-in 段由 packages/rest/src/openapi-builtin-paths.ts 从 routeManager.getAll() 产出。实测该产出不引用任何 #/components/schemas/…:

git grep -n 'components/schemas' -- packages/rest/src   →  0 hits

每个 operation 的形状是(openapi-builtin-paths.ts,operation 构造段):

• 请求体:content: { 'application/json': { schema: { type: 'object' } } },required: false;
• 响应:responses = { default: { description: RESPONSE_NOTE } }。

与此同时,静态产物贡献的 components.schemas 九条(CreateRequest / UpdateRequest / SingleRecordResponse / ListRecordResponse / DeleteResponse / ApiError / BulkRequest / BulkResponse / BaseResponse)原样进入服务出的文档 —— 但没有任何 operation 指向它们。#5744 摘除静态 paths 后,这九条在两份产物里都不再有指向者(静态产物的 $ref 数从 9 归 0)。

为什么是观察类,不是缺陷

旧的 $ref 并不是「好的、被 #5821 弄丢了」:它们挂在 0/10 命中的幽灵路径上,而且形状本身也是错的 —— { data } 信封 vs 裸记录体,packages/spec/src/api/plugin-rest-api.zod.ts 里早有记录。#5821 的取舍(「不编造:请求/响应 schema、状态码、query 参数一律不生成」)在当时是对的:路由表不携带 body 契约这一事实,凭空补上正是该单要修的那类缺陷。

所以今天没有用户会撞上错误信息 —— 只是 Scalar viewer(GET {apiPath}/docs)上 CRUD 的请求/响应从具体 schema 退成了泛 object,以及照文档生成的客户端拿不到类型。是文档质量的一次真实退化,不是正确性缺陷。

如果要修,方向长什么样

要让 body 契约回到文档里,得让路由注册携带这个事实(注册时声明 request/response schema 名,再由 buildBuiltinPaths 转成 $ref),而不是在文档产出侧按路径猜。这是新能力面,按 ADR-0049 的 enforce 路线走,需要先有真实业务拉力(谁在用生成的客户端?)。不建议在没有拉力时开工。

同族的一条小尾巴

packages/rest/src/rest-openapi-route.test.ts 里那条钉子的标题与注释在 #5744 合入后措辞过期:

• 标题:discards the static artifact section even though spec still emits it —— spec 已不再 emit;
• 注释:Leg 2 (#5744) removes the spec-side generation. Until it lands, the bundled artifact really does carry /api/{object} & co.

断言本身仍然绿且未整体空洞化:for (const path of stale) 的输入集合变成空集(实测 #5821 pin input set (stale paths): [] -> size 0),但循环之后的三条断言(components.schemas 键集逐字相等、securitySchemes 深等、info.title 相等)仍然咬合 —— 它现在钉的是「spec 拥有的那半边原样穿过 serve 期」。只是措辞需要跟上,并且如果要保住「不许泄漏」这一层语义,得换成一条幸存段仍能触及的输入(例如构造一份带 paths 的 artifact 喂给 loadOpenApiSpec 的缓存),而不是靠静态产物继续发错段来供货。

---

关联:#5588(裁决锚点)、#5821(第一棒)、#5744 / PR #5967(第二棒)、#5078、ADR-0076、ADR-0049。

---

Generated by Claude Code

[claude]

发现分诊轮:持有(留 finding)+ 补域 domain:cli。

• 域锚定:产出面在 packages/rest/src/openapi-builtin-paths.ts 与 rest-openapi-route.test.ts —— SKILL 域表里 packages/rest 属 domain:cli 车道(与第一棒 fix(rest): /openapi.json 的 built-in 路由段改由 rest 按自身路由事实产出(#5588,裁定 C 第一棒) #5821 同座位)。⛔ 不按「openapi/spec」词汇猜成 domain:spec。
• 为什么还留着:采信正文的自评并复核其论证 —— 旧 $ref 挂在 0/10 命中的幽灵路径上且形状本身就错({data} 信封 vs 裸记录体),fix(rest): /openapi.json 的 built-in 路由段改由 rest 按自身路由事实产出(#5588,裁定 C 第一棒) #5821 的「不编造」取舍在当时是对的;今天没有用户撞上错误信息,退化面是 Scalar viewer 上 CRUD body 从具体 schema 退成泛 object。要修得让路由注册携带 body 契约(新能力面,ADR-0049 enforce 路线),正文明确「无真实业务拉力不建议开工」——PM 同意:没有拉力的新能力面不入队。
• 重启条件(缺一不可,满足其一即晋级复评):① 出现真实消费方(有人按 GET {apiPath}/openapi.json 生成客户端并报告类型缺失);② 或路由注册面因别的裁决已经开始携带 request/response schema 名 —— 届时补 $ref 从「新能力」降为「顺路兑现」。
• 一条可脱钩的小尾巴(不单独立单,记在此处):packages/rest/src/rest-openapi-route.test.ts 的用例标题与注释在 [#5588 裁 C · 第二棒] build-openapi.ts 摘除 built-in 路由段生成 —— spec 静态产物只保留 components.schemas / info / securitySchemes #5744 合入后措辞过期(「spec still emits it」/「Until it lands」),且 stale 输入集合已空。断言仍绿且未整体空洞化(components.schemas 键集、securitySchemes、info.title 三条仍咬合),故不是缺陷;下一个动该文件的人顺手订正措辞即可。若要保住「不许泄漏」那层语义,需换成幸存段仍能触及的输入(构造带 paths 的 artifact 喂 loadOpenApiSpec),那一步再评。
• 前提检查:第二棒 [#5588 裁 C · 第二棒] build-openapi.ts 摘除 built-in 路由段生成 —— spec 静态产物只保留 components.schemas / info / securitySchemes #5744 / PR fix(spec): openapi 静态产物摘除 built-in 路由段，只保留契约半边 (#5744) #5967 本轮仍在飞(spec 座位),故上述小尾巴的措辞订正须等 fix(spec): openapi 静态产物摘除 built-in 路由段，只保留契约半边 (#5744) #5967 合入后才成立,提前改会与在飞 PR 撞同文件。
• 查重:三仓比对,发布出去的 /api/v1/openapi.json 描述的 built-in 路由一条都不存在 —— 10 个 operation 真实 boot 全部 404(证伪 #5456 的「当前未漂移」) #5588(裁决锚点)/ fix(rest): /openapi.json 的 built-in 路由段改由 rest 按自身路由事实产出(#5588,裁定 C 第一棒) #5821(第一棒)/ [#5588 裁 C · 第二棒] build-openapi.ts 摘除 built-in 路由段生成 —— spec 静态产物只保留 components.schemas / info / securitySchemes #5744(第二棒)均已在正文互链,无独立重复单。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

发现分诊轮(第 2 次复评):主体判级 = 继续持有 finding,域 domain:cli 不变。但上次记在这里的「小尾巴」的前置条件已经满足**,须更正。

1. 更正上次判级里的一处过时前提

上次(13:57:14Z)的持有评论写:「第二棒 #5744 / PR #5967 本轮仍在飞(spec 座位),故上述小尾巴的措辞订正须等 #5967 合入后才成立」。

实测:PR #5967 已于 2026-08-06T13:53:59Z 合并 —— 比那条评论早了约 3 分钟。也就是说该前提在写下时就已经过时,不是此后才变的。按「诊断结论一旦公开发出又被推翻,更正要发在同样公开的位置」,在此更正。

2. 主体:两条重启条件均未达成 ⇒ 持有

• 条件 ①(出现真实消费方,有人按 GET {apiPath}/openapi.json 生成客户端并报告类型缺失):未观察到。
• 条件 ②(路由注册面已开始携带 request/response schema 名):未达成,实测复核 —— git grep -c 'components/schemas' origin/main -- packages/rest/src 仍为 0。
  零命中反查(notes 6):同一模式在 packages/spec/scripts/build-openapi.ts、lib/openapi-self-consistency.ts、openapi-self-consistency.test.ts 上有命中,扫描器正常 ⇒ packages/rest/src 侧的 0 是真实的 0。

持有理由不变:要让 body 契约回到文档里,得让路由注册携带这个事实,那是一块新能力面;正文自评「无真实业务拉力不建议开工」,分诊同意 —— 没有拉力的新能力面不入队。旧 $ref 挂在 0/10 命中的幽灵路径上且形状本身就错,#5821 的「不编造」取舍在当时是对的,今天没有用户撞上错误信息。

3. 小尾巴:现已解除阻塞,仍不单独立单

packages/rest/src/rest-openapi-route.test.ts 的过期措辞仍在 main 上:

276:  it('discards the static artifact section even though spec still emits it', ...)
277:    // Leg 2 (#5744) removes the spec-side generation. Until it lands, the

#5744/#5967 已落地,所以「spec still emits it」「Until it lands」现在都是反事实。断言仍绿且未空洞化(components.schemas 键集、securitySchemes、info.title 三条仍咬合),故仍不是缺陷,维持上次的决定:不单独立单,由下一个因其它理由动到该文件的人顺手订正措辞。与上次的唯一差别是它不再需要等任何东西 —— 同文件在飞 PR 的顾虑已随 #5967 合并消失。

⛔ 本单不指派、不派发。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code