Java 后端接口文档生成器

目标

自动扫描 Java Spring Boot 项目中的 @RestController / @Controller 类，提取每个接口的详细信息（HTTP 方法、路径、参数、请求体、响应说明、描述等），并输出一份易于阅读的 Markdown 文档，方便与前端、测试人员共享。

工作流程

步骤 1：定位源码

• 询问或自动检测 Java 源码根目录（通常为 src/main/java）。
• 可让用户指定 Controller 所在的包路径，以加速扫描。

步骤 2：解析 Controller

• 递归遍历所有 .java 文件，筛选出包含 @RestController 或 @Controller 的类。
• 对每个 Controller：
• 提取类级别 @RequestMapping 的路径前缀。
• 提取方法级别的映射注解（@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping，或 @RequestMapping 并推导 method）。
• 提取路径参数（@PathVariable）、查询参数（@RequestParam）、请求体（@RequestBody）。
• 提取 JavaDoc / 注释作为接口描述。
• 如果方法有泛型返回类型或 ResponseEntity，尝试解析响应结构。
• 如果项目中使用了 Swagger 注解（@ApiOperation, @ApiParam, @ApiResponse），优先提取其中的描述和示例。

步骤 3：生成 Markdown 文档

• 调用配套脚本 scripts/generate_api_doc.py 完成解析和文档生成。
• 文档结构：
• 项目概览（标题、版本、基础路径）
• 每个 Controller 为一个章节（一级标题），内部列出该 Controller 的所有接口。
• 每个接口包含：
• 接口名称（方法名或 @ApiOperation 值）
• 路径及 HTTP 方法（高亮显示）
• 描述（JavaDoc 第一句或注解内容）
• 请求参数表格（名称、类型、位置、必填、描述）
• 请求体示例（JSON 格式，基于实体类字段生成）
• 响应示例（从代码或注解中提取）
• 错误码说明（如有 @ApiResponse）
• 文档默认保存为 API_DOCUMENTATION.md，放在项目根目录或用户指定位置。

步骤 4：输出与提示

• 报告解析到的 Controller 数量和接口总数。
• 列出哪些接口缺少描述或示例，建议用户补充。
• 如果发现使用了 @Deprecated 注解，在文档中标记为废弃接口。

使用示例

用户：“从我的 Spring Boot 项目生成接口文档”

Claude 会定位代码、调用脚本、输出 API_DOCUMENTATION.md 并提供查看建议。

用户：“更新 API 文档”

Claude 会重新扫描并与旧文档对比，仅更新变更部分（新增/修改/删除的接口）。

依赖与限制

• 脚本基于 Python 3.8+ 标准库（re, pathlib, json, argparse），无需额外安装。
• 解析基于正则表达式，对于复杂泛型、继承接口可能不够精确，但能覆盖 90% 的常见用法。
• 推荐在项目中加入 Swagger/OpenAPI 注解以获得更丰富的文档内容。

注意事项

• 生成文档不包含认证授权细节（如 JWT 如何传递），可在文档开头手动补充说明。
• 响应示例默认生成占位数据，若需真实示例，建议在代码中使用 @ApiResponse 注解或手动修改文档。