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

1. Detect OpenAPI spec was modified
2. Run validation to catch syntax/semantic errors
3. Regenerate code for all platforms
4. Run build verification
5. 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