ClawHub

Java Api Extractor

Data & APIs

从 Java 项目中提取 Controller 层接口定义为 JSON 数据。

Install

openclaw skills install java-api-extractor

Java API Extractor

从 Java Spring Boot 项目中自动提取 Controller 层的接口定义，按照标准 JSON 模版格式输出，用于推送到产品部数据平台或前端数据接口平台。

触发场景

  • 需要从 Java 项目生成接口文档
  • 批量提取 Controller 接口定义
  • 接口文档自动化生成
  • 推送接口定义前的数据准备

核心功能

  • 扫描 Java 项目中的 Controller 类
  • 解析 Spring MVC 注解（@GetMapping, @PostMapping, @PutMapping, @DeleteMapping 等）
  • 提取接口路径、请求方法、参数定义、响应类型
  • 解析 Swagger/OpenAPI 注解（@ApiOperation, @ApiParam, @Tag 等）
  • 按照标准 JSON 模版格式输出接口数组

输出格式

[
  {
    "name": "创建用户",
    "path": "/api/user",
    "method": "POST",
    "description": "创建新用户",
    "requestParams": [
      {
        "name": "userName",
        "type": "String",
        "required": true,
        "description": "用户名"
      }
    ],
    "responseSchema": {
      "type": "object",
      "properties": {
        "userId": {
          "type": "string",
          "description": "创建的用户 ID"
        }
      }
    }
  }
]

工作流程

  1. 指定 Java 项目根目录
  2. 扫描 src/main/java 下的 Controller 类
  3. 解析每个 Controller 的接口注解
  4. 提取参数信息和响应类型
  5. 生成标准 JSON 格式输出
  6. 可选：直接推送到产品部数据平台

使用方式

自然语言（推荐）：直接告诉我需求

脚本方式：

# 提取整个项目
py scripts/extract_java_api.py --project "D:\working\coding\msa-icmp-dev-manage" --output api-definitions.json

# 提取指定包
py scripts/extract_java_api.py --project "D:\working\coding\msa-icmp-dev-manage" --package "com.example.user.controller" --output user-api.json

# 提取并直接推送
py scripts/extract_java_api.py --project "D:\working\coding\msa-icmp-dev-manage" --prdid "PRD-2026-001" --push

# 详细模式
py scripts/extract_java_api.py --project "..." --output api.json --verbose

提取指定包

node scripts/extract_java_api.js --project "D:\working\coding\msa-icmp-dev-manage" --package "com.example.user.controller" --output user-api.json

提取并直接推送

node scripts/extract_java_api.js --project "D:\working\coding\msa-icmp-dev-manage" --prdid "PRD-2026-001" --push


**详细模式**：
```bash
python3 scripts/extract_java_api.py --project "..." --output api.json --verbose

支持的注解

请求映射

注解说明
@GetMappingGET 请求映射
@PostMappingPOST 请求映射
@PutMappingPUT 请求映射
@DeleteMappingDELETE 请求映射
@PatchMappingPATCH 请求映射
@RequestMapping通用请求映射
@RestControllerREST 控制器标识
@Controller控制器标识

参数注解

注解说明
@PathVariable路径参数
@RequestParam查询参数
@RequestHeader请求头参数
@RequestBody请求体
@ModelAttribute模型属性

文档注解

注解说明
@ApiOperation接口描述（Swagger 2）
@Operation接口描述（OpenAPI 3）
@ApiParam参数描述（Swagger 2）
@Parameter参数描述（OpenAPI 3）
@Tag模块标签
@Api类级别描述

参数类型映射

Java 类型JSON 类型
Stringstring
Integer, int, Long, longinteger
Boolean, booleanboolean
Double, double, Float, floatnumber
Date, LocalDateTimestring (date-time)
Listarray
Objectobject

相关文档

技术说明

首选 Python 版本：

  • Python 版本 (extract_java_api.py)：默认和首选，功能更完整，提取的接口更多（82 vs 47）
  • Node.js 版本 (extract_java_api.js)：备用选项，适合没有 Python 环境的场景

两个版本输出格式完全一致，可互换使用。

最佳实践

  • 提取前检查：确保项目已编译，依赖完整
  • Swagger 优先：有 Swagger 注解时优先使用其描述
  • 类级别路径：正确处理 @RequestMapping 在类级别的定义
  • 参数推断：无注解描述时从字段名和类型推断
  • 响应分析：从 Controller 方法返回类型推断响应结构

错误处理

  • 语法错误：跳过无法解析的类，记录警告
  • 类型缺失：使用 Object 类型占位
  • 循环依赖：检测并避免无限递归
  • 文件编码：自动检测 UTF-8/GBK
More in Data & APIs