# QA API Contract Curator

> Manage and formalize API contracts from existing endpoints, swagger/JSON, network traffic, or developer interviews into OpenAPI specifications.

- Skill: `azanir/qa-api-contract-curator` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add azanir/qa-api-contract-curator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azanir/qa-api-contract-curator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: azanir (https://skillmd.com/u/azanir)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/azanir/qa-api-contract-curator

---


# 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

1. **Collect endpoint data** — Gather from one or more input sources; merge and deduplicate.
2. **Normalize into OpenAPI 3.x** — Convert all data into a single OpenAPI 3.x specification (YAML preferred).
3. **Validate schema completeness** — Ensure paths, schemas, parameters, and responses are documented; flag gaps.
4. **Detect breaking changes** — Compare against previous version (if available); produce breaking change report.
5. **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:

- [ ] All endpoints are documented (paths, methods, parameters)
- [ ] Request/response examples provided for each operation
- [ ] Error responses defined (4xx, 5xx) where applicable
- [ ] Authentication documented (security schemes, scopes)
- [ ] Versioning strategy defined (info.version, deprecation notes)
- [ ] Schemas are complete (no `{}` or placeholder types)
- [ ] Breaking change report included when comparing versions

## 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 examples
- `references/breaking-changes.md` — Catalog of breaking changes and mitigation strategies