CLAUDE.md

1# dotCMS REST API Guide for Claude AI
2 
3## 📋 Essential Reference
4 
5**👉 REQUIRED: Read [README.md](./README.md) for comprehensive REST API development guidelines**
6 
7This file contains **AI-specific instructions only**. You MUST follow all patterns, standards, and checklists in README.md.
8 
9---
10 
11## 🤖 AI-Specific @Schema Rules
12 
13### Quick Decision Matrix
14 
15| Method Returns | Use @Schema |
16|---------------|-------------|
17| `ResponseEntity<UserView>` | `implementation = ResponseEntityUserView.class` |
18| `ResponseEntity<List<T>>` | `implementation = ResponseEntityListView.class` |
19| `List<MyEntity>` | `implementation = MyEntityListView.class` ¹ |
20| `Map<String, MyType>` | `implementation = MapStringMyTypeView.class` ¹ |
21| `Map<String, Object>` | `type = "object", description = "..."` |
22| `JSONObject` / AI APIs | `type = "object", description = "...", example = "..."` |
23 
24¹ *Create if doesn't exist: `class MyEntityListView extends ArrayList<MyEntity>`*
25 
26### 🚨 FORBIDDEN for AI
27 
28```java
29❌ @Schema(implementation = Object.class)     // Use type = "object" instead
30❌ @Schema(implementation = Map.class)        // Use specific view class
31❌ @Schema(implementation = HashMap.class)    // Use specific view class
32❌ Missing descriptions on type = "object"    // Always add description
33```
34 
35### ✅ AI Description Requirements
36 
37For `@Schema(type = "object")`:
38- **Analyze the method's business logic** to understand what data is returned
39- **Be specific**: "AI search results with contentlets and fragments" not "JSON object"  
40- **Add examples** for complex AI/external API responses
41- **Pattern**: "[Service] [operation] response containing [specific data] and [metadata]"
42 
43---
44 
45## 🎯 AI Workflow
46 
471. **READ** [README.md](./README.md) patterns and requirements
482. **ANALYZE** method return statement - wrapped vs unwrapped?
493. **CHECK** if specific view class exists for the return type
504. **APPLY** correct @Schema from decision matrix above
515. **VERIFY** against [README.md checklist](./README.md#summary-checklist)
52 
53### Critical AI Verification
54- ✅ Schema matches actual return type (not generic Object.class)
55- ✅ All `type = "object"` have meaningful descriptions
56- ✅ Descriptions explain actual data structure
57- ✅ No deprecated Object.class/Map.class patterns remain
58 
59**Goal**: Create precise API documentation that helps developers understand exactly what each endpoint returns.