直接根据密封类元数据生成OpenAPI契约文档，核心是通过KSP编译期反射递归解析其子类型拓扑，生成带discriminator的oneOf schema并注入主文档，配套运行时验证与CI一致性检查。
直接根据密封类（sealed class）的元数据生成外部 API 契约文档，核心在于：**把 Kotlin/Java 的类型结构（尤其是密封类的继承关系）映射为 OpenAPI 可描述的 schema，并自动化输出 JSON/YAML 格式文档**。不需要手写 Swagger 注解或重复维护契约，关键靠编译期反射 + 模板生成。
提取密封类的完整类型拓扑
密封类本质是一组有限、已知的子类型集合。要生成准确契约，必须递归解析其所有直接子类（包括对象、数据类、嵌套密封类），并识别：
- 每个子类是否为
data class（决定是否展开为属性字段） - 是否存在嵌套密封类（需递归展开，避免循环引用）
- 是否有
@Serializable或自定义序列化注解（影响字段可见性与命名策略） - 字段是否带
@JvmField、@JsonProperty等元数据（用于修正 OpenAPI 字段名与类型）
用 KSP 或 KAPT 生成 OpenAPI Schema 片段
推荐使用 Kotlin Symbol Processing (KSP)，它比 KAPT 更快、更安全，且原生支持密封类结构分析：
- 遍历
KSClassDeclaration，过滤出isSealed且isData为 false 的类（即密封类本身） - 调用
getSealedSubclasses()获取全部子类型，再对每个子类生成独立的schema对象 - 为整个密封类生成一个联合 schema（如 OpenAPI 3.1 的
oneOf），每个子项对应一个$ref到其子类 schema - 生成时自动添加
discriminator（例如基于type字段），便于客户端反序列化
集成到构建流程并导出标准 OpenAPI 文档
生成的 schema 片段需合并进主 OpenAPI 文档（如 openapi.yaml）。可采用两种方式：
-
增量注入：KSP 生成一个
sealed-schemas.json，构建后由 Gradle 任务读取并 patch 到主文档的components.schemas下 -
全量生成：用 Kotlin 脚本（如
generate-openapi.kts）在processResources阶段执行，扫描所有标注了@ApiContract的密封类，输出完整 YAML - 确保生成内容符合 OpenAPI 规范：字段类型映射正确（
Long→integer，LocalDateTime→string+format: date-time），枚举值展开，nullable 字段标记"nullable": true
配套支持：运行时验证与文档一致性检查
光有文档不够，还要防止代码与契约脱节：
- 在单元测试中加载生成的 OpenAPI 文档，用
swagger-parser校验语法，并断言密封类所有子类都被包含在oneOf中 - 结合
springdoc-openapi或microprofile-openapi，让运行时 API 文档自动包含这些 schema（需注册自定义SchemaCustomizer） - CI 中加入 diff 检查：每次 PR 提交后比对新旧 OpenAPI 文件，若密封类结构变更但文档未更新，则失败
