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 产物门禁)同现场但不是同一件事:那张卡问的是产物的存在性/新鲜度门禁,本条只是注释与实现脱节。不建议搭车修。

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions