mrapids 0.1.31

Your OpenAPI, but executable
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# Validate Command - Quick Reference

## 🚀 Quick Start

```bash
# Basic validation
mrapids validate api.yaml

# Strict mode (CI/CD ready)
mrapids validate --strict api.yaml

# Full lint mode (best practices)
mrapids validate --lint api.yaml
```

## 📊 Validation Levels

| Level | Flag | Use Case | Checks |
|-------|------|----------|--------|
| **Quick** | (default) | Development | Basic structure |
| **Standard** | `--strict` | CI/CD | All errors |
| **Full** | `--lint` | Quality | Errors + warnings |

## ❌ Errors Detected (Block Execution)

### 1. Undefined References
```yaml
$ref: '#/components/schemas/NonExistent'  # ❌ Doesn't exist
```

### 2. Duplicate Operation IDs
```yaml
paths:
  /users:
    get:
      operationId: getItems  # ❌ Duplicate!
  /products:
    get:
      operationId: getItems  # ❌ Same ID!
```

### 3. Type Constraint Violations
```yaml
age:
  type: string
  minimum: 0  # ❌ Numeric constraint on string!
```

### 4. Missing Path Parameters
```yaml
/users/{id}:  # ❌ {id} not defined in parameters
  get:
    parameters: []
```

## ⚠️ Warnings (Best Practices)

- Missing descriptions
- Missing examples
- Naming conventions
- Unused schemas
- HTTP vs HTTPS
- Missing security

## 🎯 Common Use Cases

### CI/CD Pipeline
```yaml
# GitHub Actions
- run: mrapids validate --strict api.yaml
```

### Pre-commit Hook
```bash
#!/bin/bash
mrapids validate --lint api.yaml || exit 1
```

### Automated Testing
```bash
mrapids validate --format json api.yaml | jq -e '.valid'
```

## 📤 Output Formats

### Text (Default)
```
❌ Errors found:
  • Schema 'User' is not defined
    at $.paths./users.get.responses.200

📈 Summary: 1 error, 0 warnings
```

### JSON (`--format json`)
```json
{
  "valid": false,
  "errors": [{
    "code": "undefined-schema",
    "message": "Schema 'User' is not defined",
    "path": "$.paths./users.get.responses.200"
  }]
}
```

## 🎮 Keyboard Shortcuts

| Task | Command |
|------|---------|
| Quick check | `mrapids validate api.yaml` |
| Pre-commit | `mrapids validate --strict api.yaml` |
| Full review | `mrapids validate --lint api.yaml` |
| CI/CD check | `mrapids validate --strict --format json api.yaml` |

## 💡 Pro Tips

1. **Start Simple**: Use basic validation during development
2. **Enforce Standards**: Use `--strict` in CI/CD
3. **Quality Gate**: Require `--lint` for releases
4. **Automate**: Add to pre-commit hooks
5. **Monitor**: Track validation metrics over time

## 🔧 Troubleshooting

| Issue | Solution |
|-------|----------|
| "Schema not found" | Check spelling and `$ref` path |
| "Duplicate ID" | Rename operations uniquely |
| "Type mismatch" | Fix constraint/type combination |
| "Path param missing" | Add parameter definition |

## 📚 Related Commands

- `mrapids gen sdk` - Generate SDK after validation
- `mrapids diff` - Compare API versions
- `mrapids resolve` - Resolve all references

## 🚦 Exit Codes

- `0` - Validation passed
- `1` - Errors found (or warnings with --strict)