| name | openapi-workflow |
| description | Proactive OpenAPI workflow. Triggers when OpenAPI spec files are modified to validate, regenerate code, and verify builds. |
OpenAPI Workflow Skill
Automatically runs the OpenAPI workflow when spec files are modified.
When to Activate
This skill should activate when:
- Files in
backend/api/*.yaml are modified
- New endpoints are added to OpenAPI spec
- Request/response schemas are changed
- User asks to add/modify API endpoints
OpenAPI Spec Location
| Type | Path | Purpose |
|---|
| API Spec | backend/api/openapi.yaml | Public API definition |
Workflow Steps
1. Validate Spec
python3 scripts/openapi_workflow.py --validate
2. Generate Code (All Platforms)
python3 scripts/openapi_workflow.py --codegen
This generates:
- Backend (Go):
backend/internal/generated/
- iOS (Swift):
mobile/ios/App/Generated/
- Android (Kotlin):
mobile/android/app/src/main/java/.../generated/
- Web (TypeScript):
web/src/generated/
3. Build Verification
python3 scripts/openapi_workflow.py --build
4. Full Workflow (All Steps)
python3 scripts/openapi_workflow.py --full
Critical Rules
| Rule | Why |
|---|
| Define response schemas properly | Inline schemas don't generate reusable types |
| Use plural file names | REST convention: users.yaml not user.yaml |
| Always regenerate after spec changes | Generated code must match spec |
| Verify ALL platforms build | API changes affect backend + iOS + Android + web |
Process
- Detect OpenAPI spec was modified
- Run validation to catch syntax/semantic errors
- Regenerate code for all platforms
- Run build verification
- Report any failures
Output Format
## OpenAPI Workflow Results
**Spec Modified**: [file path]
**Validation**: ✅ Passed / ❌ Failed
**Code Generation**: ✅ All platforms / ❌ Failed for [platform]
**Build Verification**: ✅ All platforms / ❌ Failed for [platform]
[Details of any failures]
Reference
- Script:
scripts/openapi_workflow.py
- Spec:
backend/api/openapi.yaml
