docs(rest): openapi-endpoints 的 requestBody 注释改写为实测状态——服务出的文档里 $ref 为 0 (#6797)

那句「六个内置 $ref 可以解析」在 #5588(ruling C)/ #5744 之后已经失真:内置路由段
改由 buildBuiltinPaths 在服务期生成且一个 $ref 都不发,产物侧也不再发射 paths。
本次实测:服务出的文档 $ref 总数为 0(空载 67 条 path / 展开后 88 条),静态产物
内部同样为 0,九个契约 schema 是一座无入边的孤岛。

该句是承重散文——它为紧邻的自由形态 `type: object` 决策背书,失真会让下一个读者
以为文档里存在可解析的引用图。改写后按实测状态陈述,并说明它是结构性的(装配链路
上没有任何一步发射 $ref),紧邻的 requestBody 决定因此有了更站得住的理由。

仅注释改动,无代码变更。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AZgRyPVwi1jLb1mNNuUQ9o

Author: claude

packages/rest/src/openapi-endpoints.ts

@@ -256,13 +256,25 @@ export function buildEndpointOperation(
   if (facts.readsBody && BODY_METHODS.has(endpoint.method)) {
     // Free-form object, deliberately: the executor forwards the body (through
     // `inputMapping`, when declared) to the same pipeline the built-in route
-    // uses, and this document has no PER-OBJECT schemas to point at. Since
-    // #5168 `components.schemas` is no longer empty — it carries the nine
-    // contract schemas, and the six built-in `$ref`s resolve — but those are
-    // the generic CRUD envelopes (`CreateRequest`, `ApiError`, …), not the
-    // shape of `showcase_task`'s body. An empty `type: object` says "a JSON
-    // object, shape not described here", which is true; naming fields we have
-    // not derived would not be.
+    // uses, and this document has no PER-OBJECT schemas to point at.
+    //
+    // Since #5168 `components.schemas` is no longer empty — it carries the
+    // nine contract schemas — but they are an ISLAND: the served document
+    // contains ZERO `$ref`s, so nothing in it points INTO them (#6797,
+    // re-measured against the real `GET /openapi.json` handler and against
+    // the static artifact, both 0). That is structural rather than an
+    // oversight — no step of the assembly emits one. Since #5588 (ruling C)
+    // the built-in section is produced at request time by `buildBuiltinPaths`,
+    // which emits none DELIBERATELY: the artifact's old section pointed at
+    // `CreateRequest`/`UpdateRequest` and was wrong about the wire shape those
+    // routes accept (`openapi-builtin-paths.ts`, "What it will NOT say"). And
+    // #5744 stopped the generator emitting `paths` at all.
+    //
+    // So there is no reference graph to hang a body schema on; and the nine
+    // are generic CRUD envelopes (`ApiError`, …) rather than the shape of
+    // `showcase_task`'s body in any case. An empty `type: object` says "a
+    // JSON object, shape not described here", which is true; naming fields we
+    // have not derived would not be.
     operation.requestBody = {
       required: true,
       content: { 'application/json': { schema: { type: 'object' } } },