用途
该技能用于从 OpenAPI 3 规范生成 Spring Boot（Java）应用，遵循“规格优先”原则：OpenAPI 文件是唯一事实来源，构建时仅生成接口与 DTO，生成代码不提交仓库，业务实现由开发者手写。已用 Spring Boot 4.0.8 与 4.1.1、openapi-generator 7.26.0（Maven 插件、Gradle Groovy 与 Kotlin DSL）、JDK 21+ 验证。
主要流程
准备：若已有 pom.xml / build.gradle(.kts)，沿用其构建工具与 Spring Boot 版本，不隐式升级，仅追加生成器插件；否则用 create-spring-boot-java-project 技能创建项目（依赖：web、validation、actuator，按需加 data-jpa、postgresql、security）。获取规范（文件、URL 或粘贴），保存为 src/main/resources/openapi/<name>.yaml，支持 3.0.x 与 3.1.x，Swagger 2.0 需先转换。仅询问规范未回答的问题：持久化（内存 vs 数据库）、认证、包名。
审查规范：检查唯一 operationId（成为方法名）、tags（每个生成一个接口）、可复用组件与 schema、required 列表、校验约束（minLength、maximum、pattern）、错误响应与 securitySchemes；发现问题应修改规范而非生成代码。
配置生成器：在属性中固定版本。Maven 在 <build><plugins> 中、spring-boot-maven-plugin 之前添加 openapi-generator-maven-plugin，关键配置包括 generatorName=spring、apiPackage、modelPackage、generateSupportingFiles=false，以及 interfaceOnly=true、requestMappingMode=api_interface、useSpringBoot4=true、useJackson3=true、useSpringBuiltInValidation=true、useTags=true、skipDefaultInterface=true、openApiNullable=false、documentationProvider=none、annotationLibrary=none。Gradle 使用插件 org.openapi.generator 版本 7.26.0，配置项同义（Groovy 与 Kotlin DSL 写法不同），并将生成目录加入 sourceSets，使 compileJava 依赖 openApiGenerate。
关键选项说明：Spring Boot 3.x 去掉 useSpringBoot4 与 useJackson3（useSpringBoot3=true 为默认）；Boot 4 需两者，Jackson 3 仅允许与 useSpringBoot4 同用。请求参数校验：Boot 3.2+/4 保持 useSpringBuiltInValidation=true，由 MVC 经 HandlerMethodValidationException 处理受约束的查询/路径参数；Boot 3.0/3.1 设为 false，保留 AOP 校验并显式将参数 ConstraintViolationException 映射为 400。requestMappingMode=api_interface 将类级基础路径映射放在接口上，避免与 controller、context-path 或代理重复加前缀。delegatePattern 也可用但更复杂，且需去掉 skipDefaultInterface 并处理 ApiUtil 等支持文件问题。openApiNullable=false 可避免 jackson-databind-nullable 依赖，仅当规范含可空字段 PATCH 语义时保留 true。生成模型使用 jakarta.validation，需 classpath 中有 spring-boot-starter-validation。仅在 schema 需映射到已有类时使用 importMappings/typeMappings。
实现：每个生成的 <Tag>Api 接口对应一个 @RestController 实现，不额外添加映射注解；控制器保持精简，逻辑放 @Service，返回 DTO 而非实体，必要时显式映射（项目已用 MapStruct 可用）。持久化默认按要求决定，数据库方案使用独立于 DTO 的 Spring Data JPA 实体与仓库。错误处理用 @RestControllerAdvice，保留每个操作声明的错误状态、媒体类型与响应 schema，处理 MethodArgumentNotValidException 及 HandlerMethodValidationException；仅当规范声明时返回 RFC 9457 ProblemDetail。安全按 securitySchemes 用 spring-security 技能映射，未声明 scopes 时不生成 useSpringSecurityPreAuthorize。禁止编辑生成源码，应改规范或生成器选项后重建。
测试与验证：按 spring-boot-testing 技能，用 @WebMvcTest 按控制器切片（mock 服务）、@SpringBootTest + MockMvc 覆盖正常路径与每个写操作的一个校验失败、Testcontainers 配合 @ServiceConnection 测试数据库代码。覆盖规范的每个操作（成功、未找到、无效输入），对错误响应断言声明的状态、内容类型与响应体 schema。可选用 openapi-generator validate 在 CI 中校验规范。运行 ./mvnw verify 或 ./gradlew build，启动后 curl 一个端点及 /actuator/health，并包含一个非根 server URL 的端点以验证完整路径。最后报告发现的规范问题、生成器版本与选项、写入文件及待办事项。
适用场景与限制
适用于以 OpenAPI 3 定义为契约的 Java/Spring Boot 后端项目，尤其是需要接口与模型随规范同步、避免手写样板代码的团队。限制：Swagger 2.0 需先转换；生成代码不可手改；部分选项与 Boot 版本强相关，需按说明组合；数据库、认证等需按规范与项目需求补充。