spring-ai-alibaba
diff --git a/‎.claude/skills/http-generate/SKILL.md‎
Lines changed: 279 additions & 0 deletions b/‎.claude/skills/http-generate/SKILL.md‎
Lines changed: 279 additions & 0 deletions
@@ -0,0 +1,279 @@
+---
+name: http-generate
+description: Generates HTTP request examples for Spring Boot Web interfaces according to task specification and saves them as .http files in module-generate.md directories
+---
+
+# HTTP Generator
+
+This skill automatically analyzes Spring Boot Web controllers and generates HTTP request examples for all REST endpoints, saving them as `.http` files in their respective module directories according to the task specification.
+
+## When to Use
+
+Use this skill when you need to:
+- Generate API documentation for testing
+- Create HTTP request examples for new modules
+- Document existing Spring Boot REST controllers
+- Provide ready-to-use request samples for developers
+- Automate API testing setup
+- Create interface specifications for team collaboration
+
+## How to Use
+
+### Generate HTTP Requests for a Single Module
+
+Execute the HTTP generator script to create request examples for all controllers in a module:
+
+```bash
+python .claude/skills/http-generate/scripts/http_generator.py <module_path> [output_file]
+```
+
+### Generate HTTP Requests for All Modules
+
+Use the `all` parameter to automatically discover and generate HTTP files for all modules with controllers:
+
+```bash
+python .claude/skills/http-generate/scripts/http_generator.py all
+```
+
+**Parameters:**
+- `module_path` (required): Path to the Spring Boot module directory, or `all` to process all modules
+- `output_file` (optional): Custom output file path (default: `{module_name}.http`)
+
+**Examples:**
+```bash
+# Generate for chat module-generate.md (creates basic/chat/chat.http)
+python .claude/skills/http-generate/scripts/http_generator.py basic/chat
+
+# Generate for all modules automatically
+python .claude/skills/http-generate/scripts/http_generator.py all
+
+# Generate for graph module-generate.md (creates graph/graph.http)
+python .claude/skills/http-generate/scripts/http_generator.py graph/parallel
+
+# Generate with custom output file
+python .claude/skills/http-generate/scripts/http_generator.py basic/chat custom-api.http
+
+# Generate for different modules
+python .claude/skills/http-generate/scripts/http_generator.py basic/tool
+python .claude/skills/http-generate/scripts/http_generator.py basic/image
+python .claude/skills/http-generate/scripts/http_generator.py graph/stream
+```
+
+### Supported Controller Patterns
+
+The skill automatically detects and generates requests for:
+
+#### HTTP Methods
+- **GET** `@GetMapping` - Query operations
+- **POST** `@PostMapping` - Create operations
+- **PUT** `@PutMapping` - Update operations
+- **DELETE** `@DeleteMapping` - Delete operations
+
+#### Parameter Types
+- **`@RequestParam`** with default values
+- **`@RequestParam`** without default values
+- **`@PathVariable`** for path parameters
+- **URL encoding** for Chinese characters and special values
+
+#### Controller Annotations
+- **`@RestController`** - JSON API endpoints
+- **`@Controller`** - MVC controllers
+- **`@RequestMapping`** - Base path mapping
+
+### Output Format (Task Specification)
+
+The skill generates `.http` files according to the task specification format:
+
+#### Basic Format
+```http
+# {Controller类名}的{方法名}方法
+{HTTP_METHOD} {完整URL路径}?{参数键值对}
+
+###
+# {Controller类名}的{方法名}方法
+{HTTP_METHOD} {完整URL路径}?{参数键值对}
+```
+
+#### Generated Example
+```http
+# ChatController类的callChat方法
+GET http://localhost:8080/basic/chat/call?query=你好，很高兴认识你，能简单介绍一下自己吗？
+
+###
+# ChatController类的streamChat方法
+GET http://localhost:8080/basic/chat/stream?query=你好，很高兴认识你，能简单介绍一下自己吗？
+
+###
+# ChatController类的callOption方法
+GET http://localhost:8080/basic/chat/call/option?query=你好，很高兴认识你，能简单介绍一下自己吗？
+```
+
+### Generated Request Features
+
+Each generated HTTP request includes:
+
+- **Method Documentation**: Comment format `# Controller类名的方法名方法`
+- **Complete URL**: Full endpoint URL with base path
+- **Default Parameters**: All @RequestParam values with defaults
+- **Proper Encoding**: URL encoding for Chinese characters
+- **Query String**: Properly formatted parameter strings with `?` and `&`
+- **Separators**: `###` used to separate different interfaces
+- **File Organization**: Grouped by controller and module
+
+### Module Discovery
+
+The skill automatically:
+
+1. **Discovers Modules**: Scans project directories for modules containing controllers
+2. **Identifies Controllers**: Files ending with `Controller.java`
+3. **Analyzes Annotations**: Extracts mapping annotations
+4. **Extracts Parameters**: Finds @RequestParam configurations
+5. **Builds URLs**: Constructs complete request URLs
+6. **Generates Examples**: Creates ready-to-use HTTP requests
+
+### Supported Spring Boot Patterns
+
+#### Example 1: Simple GET Controller
+```java
+@RestController
+@RequestMapping("/basic/chat")
+public class ChatController {
+
+    @GetMapping("/call")
+    public String callChat(
+        @RequestParam(value = "query",
+                    defaultValue = "你好，很高兴认识你，能简单介绍一下自己吗？",
+                    required = false) String query) {
+        return chatClient.prompt(query).call().content();
+    }
+}
+```
+
+**Generated Request:**
+```http
+# ChatController类的callChat方法
+GET http://localhost:8080/basic/chat/call?query=你好，很高兴认识你，能简单介绍一下自己吗？
+```
+
+#### Example 2: Complex Parameters
+```java
+@GetMapping("/expand-translate")
+public Map<String, Object> expandAndTranslate(
+        @RequestParam(value = "query", defaultValue = "你好", required = false) String query,
+        @RequestParam(value = "expander_number", defaultValue = "3", required = false) Integer expanderNumber,
+        @RequestParam(value = "translate_language", defaultValue = "english", required = false) String translateLanguage) {
+    // implementation
+}
+```
+
+**Generated Request:**
+```http
+# ParallelController类的expandAndTranslate方法
+GET http://localhost:8080/graph/parallel/expand-translate?query=你好&expander_number=3&translate_language=english
+```
+
+#### Example 3: Multiple Controllers
+For modules with multiple controllers, the skill generates requests for all with `###` separators:
+
+```http
+# TimeController类的call方法
+GET http://localhost:8080/basic/tool/time/call?query=请告诉我现在北京时间几点了
+
+###
+# TimeController类的callToolFunction方法
+GET http://localhost:8080/basic/tool/time/call/function?query=请告诉我现在北京时间几点了
+
+###
+# SearchController类的search方法
+GET http://localhost:8080/basic/tool/search?query=Spring+AI
+```
+
+## File Organization (Task Specification)
+
+### Output Location
+- **Default**: `{module_name}/{module_name}.http`
+- **File Naming**: Uses module name as filename (e.g., `chat.http`, `tool.http`)
+- **Custom**: User-specified path
+- **Encoding**: UTF-8 for Chinese characters
+
+### Directory Structure Example
+```
+basic/
+├── chat/
+│   ├── chat.http          ← Generated file
+│   └── src/main/java/.../ChatController.java
+├── tool/
+│   ├── tool.http          ← Generated file
+│   └── src/main/java/.../TimeController.java
+└── image/
+    ├── image.http         ← Generated file
+    └── src/main/java/.../ImageController.java
+```
+
+### Task Specification Compliance
+
+The generated files strictly follow the task specification:
+
+1. **文件命名**: 以模块名称命名，使用 `.http` 后缀 ✅
+2. **文件位置**: 放置在对应模块的根目录下 ✅
+3. **内容来源**: 基于 Controller 类中的接口方法生成 ✅
+4. **注释格式**: 使用 `# Controller类名的方法名方法` ✅
+5. **分隔符**: 使用 `###` 分隔不同接口 ✅
+6. **参数处理**: 正确处理查询参数拼接 ✅
+
+## Integration with Development Workflow
+
+### Use with IDE HTTP Client
+The generated `.http` files work seamlessly with:
+- **IntelliJ IDEA HTTP Client**
+- **VS Code REST Client**
+- **Postman Import**
+- **curl commands**
+
+### Automated Documentation
+Perfect for:
+- **API documentation generation**
+- **Testing automation**
+- **Developer onboarding**
+- **Contract testing**
+- **Integration testing setup**
+
+## Customization Options
+
+### Modify Script Behavior
+Edit `scripts/http_generator.py` to customize:
+
+- **Base URL**: Change from `http://localhost:8080`
+- **Output Format**: Modify request template according to specification
+- **Parameter Handling**: Add support for other annotations
+- **File Patterns**: Change controller detection logic
+- **Encoding**: Adjust URL encoding rules
+
+### Extend Functionality
+Add support for:
+- **POST body parameters**
+- **Header handling**
+- **Authentication headers**
+- **Multi-parameter requests**
+- **File upload examples**
+
+## Notes
+
+- The script automatically discovers all modules with controllers when using `all` parameter
+- Only processes files ending with `Controller.java`
+- Supports UTF-8 encoding for Chinese parameters
+- Requires Python 3 and no external dependencies
+- Handles complex Spring Boot annotation patterns
+- Preserves parameter defaults from source code
+- Groups requests by controller for clarity
+- Follows task specification format exactly
+
+## Error Handling
+
+Common issues and solutions:
+
+- **No controllers found**: Ensure module contains `*Controller.java` files
+- **Missing @RequestMapping**: Controllers without base mapping will use root path
+- **Complex parameters**: Some advanced parameter types may need manual adjustment
+- **Encoding issues**: Chinese characters are automatically URL-encoded
+- **Module discovery**: Use `all` parameter to auto-discover modules with controllers