用途:从运行中的后端刷新 Umbraco CMS 的 src/Umbraco.Cms.Api.Management/OpenApi.json(逐字节写入),并可选重新生成后台 hey-api 客户端,替代旧的手动复制粘贴流程。OpenAPI 端点:https://localhost:44339/umbraco/openapi/management.json(默认 44339,HTTPS 开发证书);仅在非 Production 环境映射,Production 下返回 404。
主要能力:探测后端是否在线;必要时在后台启动后端;逐字节抓取规范到目标文件;展示 git diff;仅当由本技能启动时才停止后端;可选重新生成 hey-api 客户端并检查同步状态。
使用方式(从含 umbraco.sln 的仓库根目录运行):
- 探测:curl -sk --max-time 5 -o /dev/null -w "%{http_code}" "https://localhost:44339/umbraco/openapi/management.json";200 复用现有后端,000 自行后台启动:dotnet run --project src/Umbraco.Web.UI --no-launch-profile -- --environment Development --urls https://localhost:44339
- 抓取:npm --prefix src/Umbraco.Web.UI.Client run generate:openapi -- --wait(可传非默认端口 URL 作为第一个参数);失败非零退出,直接报告脚本消息,勿重试。
- 查看改动:git diff --stat -- src/Umbraco.Cms.Api.Management/OpenApi.json
- 重新生成客户端(需先征得同意):npm --prefix src/Umbraco.Web.UI.Client run generate:server-api 与 git diff --stat -- src/Umbraco.Web.UI.Client/src/packages/core/backend-api/
限制与注意:两条 npm 命令必须分开执行,不可串联——客户端生成器只读取已提交的 OpenApi.json。目标文件需已存在于仓库根目录,否则应停止并说明。抓取结果反映运行中的构建而非当前工作树,若 API 已变更需先重新构建/重启后端;[ApiExplorerSettings(IgnoreApi = true)] 的控制器(如后台安全端点 BackOfficeController 的登录、令牌、登出、授权、保活)本就不出现在文档中。文件为 JSON 合法不代表最新;不要重新格式化抓取的 JSON。该技能会访问实时服务器并可能改写生成源码,可重复运行且可经 git 恢复。若端口不可达且后端启动失败,应展示 dotnet run 输出而非盲目重试。