手头没有现成的接口文档，只有一堆 TypeScript 类型定义，却急需输出 OpenAPI 3.0 契约用于联调、Mock 或挂载到 Swagger UI？手动将 interface 翻译成 YAML 的老方法极易出错——漏字段、嵌套错位、缺少示例，反复修补比重新编写还费时。实际上，借助 CodeBuddy 可以直接从 TS 接口反向生成 OpenAPI Schema 片段，再注入到完整的 openapi.yaml 文件中，全程无需手动编写一行 YAML 结构。

具体如何操作？继续往下看。

从 TS 接口反向生成 OpenAPI Schema 片段

这一步非常适合前后端并行开发的场景——前端已经定义好响应模型，后端文档却尚未生成。CodeBuddy 能够将 type/interface 直接编译为标准 OpenAPI schema，省去手动对照的繁琐。

1、在 CodeBuddy 中打开包含目标接口类型的 TS 文件，例如 src/types/user.ts，滚动定位到 【UserDetailResponse】 interface 声明处。

2、将光标停留在 interface 关键字上 → 右键 → 选择“生成 OpenAPI Schema”。

3、CodeBuddy 会输出纯 YAML 片段，包含 type、properties、required 和 example 字段，嵌套对象与数组结构自动推导。如果字段带有 JSDoc 注释（例如 /** @example "admin@corp.com" */ email: string;），则 example 值会优先采用注释中的内容——这比手动猜测示例数据可靠得多。

将 Schema 片段整合进完整 openapi.yaml

单个 interface 生成的仅是 schema 片段，并非完整文档。你还需要将其注入 components.schemas，并关联到路径定义，这样 Swagger UI 才能正确解析。这里有两种方法可选。

方法一：CLI 手动注入

执行命令：codebuddy doc inject --schema user.yaml --target openapi.yaml --as UserDetailResponse。

该命令会定位 openapi.yaml 中的 components.schemas 节点，并将 user.yaml 的内容以 key UserDetailResponse 插入。【若 openapi.yaml 不存在，此命令会静默失败，不创建新文件】——因此请确保目标文件已存在，或事先准备好空模板。

方法二：AI 指令补全路径

在 CLI 交互模式下输入如下指令：“将以下 schema 作为 UserDetailResponse 加入 components.schemas，并为 GET /api/v1/users/{id} 添加 200 响应，content type 为 application/json，schema 引用 #/components/schemas/UserDetailResponse”。然后粘贴上一步生成的 YAML 片段，等待输出完整的 openapi.yaml。这种方式适合同时完成路径定义，省去手动编写步骤。

验证生成结果是否可用

打开 Swagger Editor（editor.swagger.io），将生成的 openapi.yaml 全文粘贴进去。逐一检查三项：路径是否出现在左侧导航栏？响应体是否展开为树形结构？每个字段的 type 和 example 是否与 TS 原始定义一致？

如果某个嵌套字段显示为 object 且无法展开，说明其类型是未导出的内联 interface——返回 TS 文件中，将该类型单独声明并 export 出来，重新生成即可。

最后运行 swagger-cli validate openapi.yaml，无报错则表示语法合规，契约正式落地。

整个过程下来，你会发现：从 TS 到 OpenAPI 的转换，完全可以实现零手动 YAML 书写。省下的时间，用来提升开发效率或摸鱼，它不香吗？