Kiro Hooks 自动生成接口文档 — 通用教程

Kiro Hooks 自动生成接口文档 — 通用教程

一、场景与目标

开发 Java 接口后，手动编写接口文档费时且容易遗漏。通过 Kiro Hook 机制，可以实现：

保存 Controller 文件 → Kiro 自动解析接口 → 生成 OpenAPI 3.0 规范文件 → 手动导入 ApiPost/Apifox

最终效果：你只需专注写代码，保存文件后 OpenAPI 文档自动生成，随时可导入接口管理工具。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

二、什么是 Kiro Hook

Hook 是 Kiro 的事件驱动自动化机制。当 IDE 中发生特定事件（文件保存、提交代码等）时，自动触发预定义的操作（让 AI 执行任务或运行命令）。

Hook 文件结构

{"name":"Hook名称","version":"1.0.0","description":"Hook描述","when":{"type":"事件类型","patterns":["触发文件模式"]},"then":{"type":"动作类型","prompt":"AI指令（askAgent时必填）","command":"命令（runCommand时必填）"}}

支持的事件类型

支持的动作类型

三、配置步骤

步骤 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

/** * 用户管理接口. */@RestController@RequestMapping("/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.yaml）

openapi: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/CreateUserParamDto'responses:'200':description:成功content:application/json:schema:$ref:'#/components/schemas/UserResultDto'components: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

1. 打开 ApiPost
2. 项目 → 导入 → 选择「OpenAPI/Swagger」格式
3. 上传docs/openapi/api-spec.yaml
4. 确认导入 → 接口自动创建完成

五、进阶：自动推送到接口管理平台（可选）

如果接口平台提供了 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_ID="YOUR_PROJECT_ID"API_TOKEN="YOUR_API_TOKEN"OPENAPI_FILE="docs/openapi/api-spec.yaml"API_URL="https://api.example.com/v1/projects/{}/import-openapi"defmain():"""主函数."""ifnotos.path.exists(OPENAPI_FILE):print(f"文件不存在:{OPENAPI_FILE}")returnprint("正在推送接口文档...")withopen(OPENAPI_FILE,"r",encoding="utf-8")asf:content=f.read()payload=json.dumps({"input":content,"options":{"targetEndpointFolderId":0,"endpointOverwriteBehavior":"methodAndPath"}}).encode("utf-8")url=API_URL.format(PROJECT_ID)req=urllib.request.Request(url,data=payload,method="POST")req.add_header("Authorization",f"Bearer{API_TOKEN}")req.add_header("Content-Type","application/json")try:withurllib.request.urlopen(req,timeout=25)asresp:result=resp.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. 说明多次触发时的去重策略（按路径+方法覆盖）

七、常见问题

问题 1：Hook 没有触发

检查项：

• 文件名是否匹配 patterns（如*Controller.java）
• Hook 的enabled是否为true
• 在 Kiro 侧边栏 Agent Hooks 中确认 Hook 状态

问题 2：生成的 YAML 格式不正确

解决：在 prompt 中明确要求"严格遵循 OpenAPI 3.0.3 规范，确保 YAML 缩进正确"。

问题 3：DTO 字段解析不完整

原因：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 自动完成。