|
| 1 | +--- |
| 2 | +name: document-api-integration |
| 3 | +description: Generate comprehensive documentation for a qontract-api integration. Use this skill when a new integration has been created or migrated to qontract-api and needs documentation, or when someone asks to document an integration. Triggers on requests mentioning integration documentation, documenting API integrations, or after completing a migration with /migrate-integration. |
| 4 | +--- |
| 5 | + |
| 6 | +# Document qontract-api Integration |
| 7 | + |
| 8 | +Analyze an existing qontract-api integration and generate documentation following the standard template at `docs/integrations/template.md`. |
| 9 | + |
| 10 | +## Input |
| 11 | + |
| 12 | +Integration name (e.g., "slack-usergroups"). If not provided, ask for it. |
| 13 | + |
| 14 | +Validate the integration exists at `qontract_api/qontract_api/integrations/<name>/` before proceeding. |
| 15 | + |
| 16 | +## Workflow |
| 17 | + |
| 18 | +1. **Read the template** from `docs/integrations/template.md` |
| 19 | + |
| 20 | +2. **Analyze the integration** by reading: |
| 21 | + - `qontract_api/qontract_api/integrations/<name>/models.py` - Request/Response/Action models |
| 22 | + - `qontract_api/qontract_api/integrations/<name>/service.py` - Business logic |
| 23 | + - `qontract_api/qontract_api/integrations/<name>/router.py` - API endpoints |
| 24 | + - `qontract_api/qontract_api/integrations/<name>/tasks.py` - Celery tasks |
| 25 | + - Other files in the integration directory (factory, client, etc.) |
| 26 | + - `reconcile/<name>_api.py` or `reconcile/<name>_api/` - Client integration |
| 27 | + - Related ADRs referenced in docstrings/comments |
| 28 | + |
| 29 | +3. **Extract information** for each template section: |
| 30 | + - **Features**: What it does, actions it can perform, resources it manages |
| 31 | + - **API Endpoints**: POST/GET paths, parameters, responses |
| 32 | + - **Models**: Pydantic structure, key fields, validation rules (dry_run default=True) |
| 33 | + - **Actions**: All action types from discriminated union models |
| 34 | + - **Architecture**: Client-side vs server-side responsibilities |
| 35 | + - **Limits/Constraints**: Safety features, rate limits, cache TTLs, managed resources |
| 36 | + - **Required Components**: Vault secrets, external APIs, environment variables |
| 37 | + |
| 38 | +4. **Generate documentation** using the template structure exactly. Fill all sections. Mark non-applicable sections as "[Not applicable for this integration]". |
| 39 | + |
| 40 | +5. **Show summary** to user before writing: |
| 41 | + - API path, features count, action types, external APIs, requirements |
| 42 | + |
| 43 | +6. **Write files** after confirmation: |
| 44 | + - Create `docs/integrations/<name>.md` |
| 45 | + - Update `docs/integrations/README.md` with link in alphabetical order |
| 46 | + |
| 47 | +## Guidelines |
| 48 | + |
| 49 | +- Follow the template structure from `docs/integrations/template.md` exactly |
| 50 | +- Extract information from actual code, not assumptions |
| 51 | +- Reference relevant ADRs |
| 52 | +- Include practical usage examples (curl commands, CLI) |
| 53 | +- Emphasize dry_run defaults and safety features |
| 54 | +- Set Last Updated date to today |
0 commit comments