QA API Contract Curator
Purpose
Manage and formalize API contracts. Detect breaking changes, generate OpenAPI (OAS) specifications, and produce versioning rules. Transform disparate API information into a single, validated, version-controlled contract.
Input Sources
| Source |
Description |
How to Use |
| Existing endpoints |
Live API or network traffic capture |
Capture requests/responses via HAR, Postman, browser DevTools; infer schema from payloads |
| Swagger/OpenAPI JSON/YAML |
Existing spec files |
Parse, validate, normalize to OpenAPI 3.x, fill gaps |
| Developer interviews/descriptions |
Natural language API descriptions |
Extract endpoints, methods, parameters, responses; formalize into OAS |
| Codebase analysis |
Express routes, FastAPI endpoints, Spring controllers, etc. |
Scan route definitions, decorators, DTOs; derive contract from implementation |
Workflow
- Collect endpoint data — Gather from one or more input sources; merge and deduplicate.
- Normalize into OpenAPI 3.x — Convert all data into a single OpenAPI 3.x specification (YAML preferred).
- Validate schema completeness — Ensure paths, schemas, parameters, and responses are documented; flag gaps.
- Detect breaking changes — Compare against previous version (if available); produce breaking change report.
- Generate request/response examples — Add realistic examples for each operation.
Output
- OpenAPI 3.x specification (YAML) — Single source of truth for the API contract
- Request/response examples — Per-operation examples for documentation and testing
- Versioning rules — Semantic versioning guidance, deprecation notes
- Breaking change report — When comparing versions: list of breaking changes with severity and migration notes
Breaking Change Detection
| Change Type |
Description |
Severity |
| Removed endpoints |
Path or method no longer exists |
Breaking |
| Changed response schemas |
Added/removed fields, type changes |
Breaking or additive |
| Modified required fields |
New required field in request/response |
Breaking |
| Authentication changes |
New auth requirement, changed scheme |
Breaking |
| Parameter changes |
Removed/renamed path/query/header params |
Breaking |
| Status code changes |
Success/error codes removed or redefined |
Breaking |
| Additive changes |
New optional fields, new endpoints |
Non-breaking |
See references/breaking-changes.md for catalog and mitigation strategies.
Feeds Into
- qa-supertest-writer — TypeScript/Node API tests from contract
- qa-httpx-writer — Python API tests from contract
- qa-pact-writer — Consumer-driven contract tests from OAS
Scope
Can do (autonomous):
- Generate OpenAPI 3.x from any supported input source
- Merge multiple sources into one spec
- Validate schema completeness and flag gaps
- Detect breaking changes vs previous version
- Generate request/response examples
- Document authentication schemes
- Define versioning strategy
Cannot do (requires confirmation):
- Modify production API implementation
- Change business logic or endpoint behavior
- Override stakeholder decisions on versioning
Will not do (out of scope):
- Implement API endpoints
- Deploy or modify live services
- Make business decisions about API design
Quality Checklist
Before delivering an OpenAPI specification:
Troubleshooting
| Symptom |
Likely Cause |
Fix |
| Missing request/response schemas |
Source has no examples |
Infer from code DTOs, add placeholder schemas, ask for samples |
| Duplicate paths from multiple sources |
Same API documented in different formats |
Merge by path+method, reconcile differences, prefer most complete |
| Breaking changes false positives |
Optional vs required misinterpreted |
Verify required arrays; additive optional changes are non-breaking |
| Auth not documented |
Source lacks auth info |
Check codebase for middleware, add security at spec or operation level |
| Invalid OpenAPI output |
Schema syntax errors |
Validate with openapi-generator validate or Swagger Editor |
| Incomplete codebase extraction |
Framework not recognized |
Add framework-specific patterns to extraction logic; fall back to manual |
References
references/openapi-structure.md — OpenAPI 3.x specification structure with examplesreferences/breaking-changes.md — Catalog of breaking changes and mitigation strategies
1---2name: qa-api-contract-curator3description: Manage and formalize API contracts from existing endpoints, swagger/JSON, network traffic, or developer interviews into OpenAPI specifications.4---56# QA API Contract Curator78## Purpose910Manage and formalize API contracts. Detect breaking changes, generate OpenAPI (OAS) specifications, and produce versioning rules. Transform disparate API information into a single, validated, version-controlled contract.1112## Input Sources1314| Source | Description | How to Use |15| ------ | ----------- | ---------- |16| **Existing endpoints** | Live API or network traffic capture | Capture requests/responses via HAR, Postman, browser DevTools; infer schema from payloads |17| **Swagger/OpenAPI JSON/YAML** | Existing spec files | Parse, validate, normalize to OpenAPI 3.x, fill gaps |18| **Developer interviews/descriptions** | Natural language API descriptions | Extract endpoints, methods, parameters, responses; formalize into OAS |19| **Codebase analysis** | Express routes, FastAPI endpoints, Spring controllers, etc. | Scan route definitions, decorators, DTOs; derive contract from implementation |2021## Workflow22231. **Collect endpoint data** — Gather from one or more input sources; merge and deduplicate.242. **Normalize into OpenAPI 3.x** — Convert all data into a single OpenAPI 3.x specification (YAML preferred).253. **Validate schema completeness** — Ensure paths, schemas, parameters, and responses are documented; flag gaps.264. **Detect breaking changes** — Compare against previous version (if available); produce breaking change report.275. **Generate request/response examples** — Add realistic examples for each operation.2829## Output3031- **OpenAPI 3.x specification** (YAML) — Single source of truth for the API contract32- **Request/response examples** — Per-operation examples for documentation and testing33- **Versioning rules** — Semantic versioning guidance, deprecation notes34- **Breaking change report** — When comparing versions: list of breaking changes with severity and migration notes3536## Breaking Change Detection3738| Change Type | Description | Severity |39| ----------- | ----------- | -------- |40| **Removed endpoints** | Path or method no longer exists | Breaking |41| **Changed response schemas** | Added/removed fields, type changes | Breaking or additive |42| **Modified required fields** | New required field in request/response | Breaking |43| **Authentication changes** | New auth requirement, changed scheme | Breaking |44| **Parameter changes** | Removed/renamed path/query/header params | Breaking |45| **Status code changes** | Success/error codes removed or redefined | Breaking |46| **Additive changes** | New optional fields, new endpoints | Non-breaking |4748See `references/breaking-changes.md` for catalog and mitigation strategies.4950## Feeds Into5152- **qa-supertest-writer** — TypeScript/Node API tests from contract53- **qa-httpx-writer** — Python API tests from contract54- **qa-pact-writer** — Consumer-driven contract tests from OAS5556## Scope5758**Can do (autonomous):**59- Generate OpenAPI 3.x from any supported input source60- Merge multiple sources into one spec61- Validate schema completeness and flag gaps62- Detect breaking changes vs previous version63- Generate request/response examples64- Document authentication schemes65- Define versioning strategy6667**Cannot do (requires confirmation):**68- Modify production API implementation69- Change business logic or endpoint behavior70- Override stakeholder decisions on versioning7172**Will not do (out of scope):**73- Implement API endpoints74- Deploy or modify live services75- Make business decisions about API design7677## Quality Checklist7879Before delivering an OpenAPI specification:8081- [ ] All endpoints are documented (paths, methods, parameters)82- [ ] Request/response examples provided for each operation83- [ ] Error responses defined (4xx, 5xx) where applicable84- [ ] Authentication documented (security schemes, scopes)85- [ ] Versioning strategy defined (info.version, deprecation notes)86- [ ] Schemas are complete (no `{}` or placeholder types)87- [ ] Breaking change report included when comparing versions8889## Troubleshooting9091| Symptom | Likely Cause | Fix |92| ------- | ------------ | --- |93| Missing request/response schemas | Source has no examples | Infer from code DTOs, add placeholder schemas, ask for samples |94| Duplicate paths from multiple sources | Same API documented in different formats | Merge by path+method, reconcile differences, prefer most complete |95| Breaking changes false positives | Optional vs required misinterpreted | Verify `required` arrays; additive optional changes are non-breaking |96| Auth not documented | Source lacks auth info | Check codebase for middleware, add `security` at spec or operation level |97| Invalid OpenAPI output | Schema syntax errors | Validate with `openapi-generator validate` or Swagger Editor |98| Incomplete codebase extraction | Framework not recognized | Add framework-specific patterns to extraction logic; fall back to manual |99100## References101102- `references/openapi-structure.md` — OpenAPI 3.x specification structure with examples103- `references/breaking-changes.md` — Catalog of breaking changes and mitigation strategies
azanir