openapi: utoipa 生成式迁移 — 从 Rust handler 生成 spec,根治手写漂移(决定 A)

[jhfnetboy]

roadmap 决定 A(jason 2026-08-18):KMS HTTP API 作为公开产品契约,用生成式 openapi。

目标

用 utoipa(或等价)在 kms/host 的 handler + 请求/响应 struct 上加注解,构建时生成 kms/docs/api/openapi.yaml,让 spec 不可能与代码漂移。

为什么

手写 openapi 已漏过 /attestation 端点、漏过 version bump(CC-106)。生成式把它从'手写文档债'变成'编译器保证的产物'——这是决定 A 划算的前提。

范围

• kms/host handler 加 utoipa 注解(路径/参数/响应 schema/鉴权)。
• 构建/CI 时生成 openapi.yaml,与入库版本比对(替代/扩展现有 ca-ta-consistency 的 version 门)。
• /docs Swagger UI + /openapi.yaml 端点继续 serve 生成产物。
• 覆盖公网端点;loopback 内部端点(/pop、/kms/sign)按现状排除或单独标注。

优先级

post-stability(版本稳定盘点 CC-30 后)。过渡期 #212 的版本门保底。

参考:docs/roadmap.md OpenAPI 决策段;PR #212(过渡版)。