Skip to content

openapi-endpoints.ts 的注释仍宣称「六个内置 $ref 可解析」——实测服务出的文档里 $ref 总数为 0(#5588 之后已失真) #6797

Description

@os-project-manager

观察类记录(finding),发现于 #5757 的测量任务(该卡是「先测量」卡,本条不在其范围内,按 Prime Directive #10 单独登记)。

事实(实测,origin/main @ e1e762971)

packages/rest/src/openapi-endpoints.ts:259:262 的注释写道:

#5168components.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 进一步让生成器不再发射 pathsbuildBuiltinPaths 明确不发任何 $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 产物门禁)同现场但不是同一件事:那张卡问的是产物的存在性/新鲜度门禁,本条只是注释与实现脱节。不建议搭车修。

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions