Swagger 页面生成

要解决什么问题

后端已经有一份 Swagger/OpenAPI 描述，但管理端 CRUD 页面往往还要手写列表、表单、字段映射和 API 封装。接口一多，重复劳动和前后端字段不一致都会拖慢迭代。

Swagger Page Gen 把「接口文档 → 可维护页面代码」做成一条可复用的生成链路：先对齐数据契约与项目约定，再按 Swagger 解析出 PageSchema，最后落到你选的 UI 库组件上。

技能如何工作

生成前有一套固定的读取顺序，避免跳过基础约束：

1. 先读 foundation/page-schema.md、coding-conventions.md、api-contract.md，明确页面数据契约、编码风格和 API 层规范。
2. 读项目根目录的 .page-gen.yml（人工维护的初始配置），并立即执行 foundation/config-validator.md，产出 .page-gen.lock.yml。
3. 后续生成与 QA 只认 lock 文件里 verified 节（例如 verified.tech.ui_library），再加载对应 adapter/*.md 与任务文档（如 workflow/swagger-to-crud.md）。

两种用法：

• 一键生成：按 workflow/swagger-to-crud.md，提供 Swagger JSON 或 URL。
• 分步生成：domain/swagger-analyzer.md 确认 PageSchema → domain/crud-*.md 搭页面结构 → adapter/*.md 写出具体 UI 代码。

| 文件 | 角色 |
|------|------|
| .page-gen.yml | 你填写的初始配置，可能与仓库现状有偏差 |
| .page-gen.lock.yml | 校验后的可信快照，生成与 QA 的唯一依据 |

适用边界与注意点

• 没有 .page-gen.yml 时，技能无法按项目约定生成；配置只需填一次，但改技术栈或目录结构后应重新校验。
• 初始 yml 与真实项目不一致时，以 lock 为准，避免生成代码引用不存在的路径或 UI 库。
• 建议将 .page-gen.lock.yml 纳入版本控制，方便团队共享「已验证」的配置状态。