Kiro Hooks 自动生成接口文档 — 通用教程一、场景与目标开发 Java 接口后手动编写接口文档费时且容易遗漏。通过 Kiro Hook 机制可以实现保存 Controller 文件 → Kiro 自动解析接口 → 生成 OpenAPI 3.0 规范文件 → 手动导入 ApiPost/Apifox最终效果你只需专注写代码保存文件后 OpenAPI 文档自动生成随时可导入接口管理工具。注博客https://blog.csdn.net/badao_liumang_qizhi二、什么是 Kiro HookHook 是 Kiro 的事件驱动自动化机制。当 IDE 中发生特定事件文件保存、提交代码等时自动触发预定义的操作让 AI 执行任务或运行命令。Hook 文件结构{name:Hook名称,version:1.0.0,description:Hook描述,when:{type:事件类型,patterns:[触发文件模式]},then:{type:动作类型,prompt:AI指令askAgent时必填,command:命令runCommand时必填}}支持的事件类型事件类型触发时机fileEdited文件保存时fileCreated文件创建时fileDeleted文件删除时userTriggered手动触发promptSubmit发送消息时agentStopAI执行完成时preToolUse工具调用前postToolUse工具调用后支持的动作类型动作类型说明askAgent向 AI 发送指令让 AI 执行任务runCommand执行 Shell 命令三、配置步骤步骤 1创建 Hook 文件在项目根目录.kiro/hooks/下创建 Hook 配置文件文件路径.kiro/hooks/generate-api-doc.kiro.hook{enabled:true,name:生成接口文档,version:1,description:当Controller文件被编辑保存时自动解析接口方法生成OpenAPI 3.0规范文件,when:{type:fileEdited,patterns:[*Controller.java,*Api.java]},then:{type:askAgent,prompt:检测到Controller文件变更。请分析该文件中新增或修改的接口方法GetMapping/PostMapping/PutMapping/DeleteMapping等为每个接口生成OpenAPI 3.0规范片段包含1.请求路径和HTTP方法 2.请求参数path/query/header 3.请求体Schema解析入参DTO的字段 4.响应体Schema解析出参DTO的字段 5.接口描述取自JavaDoc注释。将生成的内容追加到 docs/openapi/api-spec.yaml 文件中。如果该文件不存在则创建完整的OpenAPI 3.0结构。}}步骤 2创建输出目录确保项目中存在docs/openapi/目录首次触发时 Kiro 会自动创建。步骤 3验证 Hook 生效在 Kiro 侧边栏「Agent Hooks」区域应能看到新创建的 Hook。也可通过命令面板搜索Open Kiro Hook UI查看。四、完整工作流演示1. 编写 Controller/** * 用户管理接口. */RestControllerRequestMapping(/api/user)publicclassUserController{/** * 根据ID查询用户. * * param id 用户ID * return 用户信息 */GetMapping(/{id})publicUserResultDtogetUserById(PathVariableIntegerid){// 业务逻辑}/** * 创建用户. * * param paramDto 创建参数 * return 创建结果 */PostMapping(/create)publicUserResultDtocreateUser(RequestBodyCreateUserParamDtoparamDto){// 业务逻辑}}2. 保存文件 → Hook 自动触发Kiro 解析接口注解、入参 DTO、出参 DTO自动生成3. 生成的 OpenAPI 规范文件docs/openapi/api-spec.yamlopenapi:3.0.3info:title:项目接口文档version:1.0.0paths:/api/user/{id}:get:summary:根据ID查询用户tags:-用户管理parameters:-name:idin:pathrequired:truedescription:用户IDschema:type:integerresponses:200:description:成功content:application/json:schema:$ref:#/components/schemas/UserResultDto/api/user/create:post:summary:创建用户tags:-用户管理requestBody:required:truecontent:application/json:schema:$ref:#/components/schemas/CreateUserParamDtoresponses:200:description:成功content:application/json:schema:$ref:#/components/schemas/UserResultDtocomponents:schemas:CreateUserParamDto:type:objectproperties:userName:type:stringdescription:用户名phone:type:stringdescription:手机号email:type:stringdescription:邮箱UserResultDto:type:objectproperties:id:type:integerdescription:用户IDuserName:type:stringdescription:用户名phone:type:stringdescription:手机号4. 导入 ApiPost打开 ApiPost项目 → 导入 → 选择「OpenAPI/Swagger」格式上传docs/openapi/api-spec.yaml确认导入 → 接口自动创建完成五、进阶自动推送到接口管理平台可选如果接口平台提供了 Open API如 Apifox 的导入接口可以再加一个 Hook 实现全自动推送文件路径.kiro/hooks/push-api-doc.kiro.hook{enabled:true,name:推送接口文档,version:1,description:当OpenAPI规范文件变更时自动推送到接口管理平台,when:{type:fileEdited,patterns:[docs/openapi/*.yaml,docs/openapi/*.yml,docs/openapi/*.json]},then:{type:runCommand,command:python scripts/push-api-doc.py,timeout:30}}对应的推送脚本示例scripts/push-api-doc.py# -*- coding: utf-8 -*-推送 OpenAPI 规范文件到接口管理平台.importjsonimportosimporturllib.requestimporturllib.error# 配置信息替换为你的实际值PROJECT_IDYOUR_PROJECT_IDAPI_TOKENYOUR_API_TOKENOPENAPI_FILEdocs/openapi/api-spec.yamlAPI_URLhttps://api.example.com/v1/projects/{}/import-openapidefmain():主函数.ifnotos.path.exists(OPENAPI_FILE):print(f文件不存在:{OPENAPI_FILE})returnprint(正在推送接口文档...)withopen(OPENAPI_FILE,r,encodingutf-8)asf:contentf.read()payloadjson.dumps({input:content,options:{targetEndpointFolderId:0,endpointOverwriteBehavior:methodAndPath}}).encode(utf-8)urlAPI_URL.format(PROJECT_ID)requrllib.request.Request(url,datapayload,methodPOST)req.add_header(Authorization,fBearer{API_TOKEN})req.add_header(Content-Type,application/json)try:withurllib.request.urlopen(req,timeout25)asresp:resultresp.read().decode(utf-8)print(f推送成功! 响应:{result})excepturllib.error.HTTPErrorase:print(f推送失败! 状态码:{e.code}, 响应:{e.read().decode()})exceptExceptionase:print(f推送异常:{e})if__name____main__:main()六、Hook Prompt 编写技巧prompt 的质量决定了生成文档的准确性以下是关键要素1. 明确告知要解析的注解类型GetMapping / PostMapping / RequestBody / PathVariable 等 2. 指定输出格式OpenAPI 3.0 YAML 3. 说明 Schema 解析规则读取 DTO 字段、类型、JavaDoc注释 4. 指定输出路径和文件行为追加 or 覆盖 5. 说明多次触发时的去重策略按路径方法覆盖七、常见问题问题 1Hook 没有触发检查项文件名是否匹配 patterns如*Controller.javaHook 的enabled是否为true在 Kiro 侧边栏 Agent Hooks 中确认 Hook 状态问题 2生成的 YAML 格式不正确解决在 prompt 中明确要求严格遵循 OpenAPI 3.0.3 规范确保 YAML 缩进正确。问题 3DTO 字段解析不完整原因DTO 可能在其他文件中定义。解决在 prompt 中加上如果入参/出参 DTO 在其他文件中请读取对应文件解析完整字段。问题 4每次保存都重新生成全部接口解决在 prompt 中指定只处理本次变更涉及的接口方法对已存在于 yaml 中的同路径接口进行覆盖更新不影响其他接口。八、流程速查1. 创建 .kiro/hooks/generate-api-doc.kiro.hook配置触发规则和AI指令 2. 正常开发 Controller 接口 3. 保存文件 → Hook 自动触发 → AI 解析注解和DTO → 生成 docs/openapi/api-spec.yaml 4. 打开 ApiPost → 导入 → OpenAPI/Swagger → 选择 yaml 文件 → 完成整个流程中你只需要做第2步和第4步的导入操作接口文档的解析和生成完全由 Kiro 自动完成。