如何编写自动化脚手架自动根据密封类元数据生成对应的外部API契约文档-java教程-PHP中文网

直接根据密封类元数据生成openapi契约文档，核心是通过ksp编译期反射递归解析其子类型拓扑，生成带discriminator的oneof schema并注入主文档，配套运行时验证与ci一致性检查。

如何编写自动化脚手架自动根据密封类元数据生成对应的外部api契约文档

直接根据密封类（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 更快、更安全，且原生支持密封类结构分析：

鲜艺AI抠图

鲜艺AI抠图是一款AI图片处理工具，免费 AI 抠图工具，支持离线安装与使用。

下载

遍历 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 文件，若密封类结构变更但文档未更新，则失败