From d8180600a5cf11395d2f8c7f3f8fed04bf0b3c4a Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 8 Aug 2026 23:34:48 +0000 Subject: [PATCH] =?UTF-8?q?docs(rest):=20openapi-endpoints=20=E7=9A=84=20r?= =?UTF-8?q?equestBody=20=E6=B3=A8=E9=87=8A=E6=94=B9=E5=86=99=E4=B8=BA?= =?UTF-8?q?=E5=AE=9E=E6=B5=8B=E7=8A=B6=E6=80=81=E2=80=94=E2=80=94=E6=9C=8D?= =?UTF-8?q?=E5=8A=A1=E5=87=BA=E7=9A=84=E6=96=87=E6=A1=A3=E9=87=8C=20$ref?= =?UTF-8?q?=20=E4=B8=BA=200=20(#6797)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 那句「六个内置 $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 Claude-Session: https://claude.ai/code/session_01AZgRyPVwi1jLb1mNNuUQ9o --- packages/rest/src/openapi-endpoints.ts | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/packages/rest/src/openapi-endpoints.ts b/packages/rest/src/openapi-endpoints.ts index aed3bb58c9..0ca36b414f 100644 --- a/packages/rest/src/openapi-endpoints.ts +++ b/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' } } },