Generating API Contracts
Overview
Generate OpenAPI 3.0/3.1 specifications and consumer-driven contract tests from existing API implementations, design documents, or database schemas. Produce machine-readable contracts that serve as the single source of truth for code generation, documentation, testing, and gateway configuration, with Pact integration for consumer-driven contract verification.
Prerequisites
- API implementation with route definitions and handler logic, or design requirements document
- OpenAPI authoring tool: Swagger Editor, Stoplight Studio, or IDE with OpenAPI extension
- Consumer-driven contract framework: Pact (polyglot), Spring Cloud Contract (Java), or Dredd (generic)
- Schema validation tool: Spectral for OpenAPI linting
- Version control for contract files with diff-based review process
Instructions
- Scan existing route handlers and controller files using Grep and Read to extract all endpoint paths, HTTP methods, request parameter names/types, and response body shapes.
- Generate OpenAPI 3.0 specification from the extracted data, including
info (title, version, description), servers (environment URLs), paths (operations), and components (reusable schemas).
- Define request schemas with field-level constraints:
type, format, required, minimum/maximum, pattern (regex), enum, and example values for every property.
- Document all response status codes per endpoint with separate schemas: 200/201 for success, 400 for validation errors (with field-level error array), 401/403 for auth failures, and 404/500.
- Add security scheme definitions (
bearerAuth, apiKey, oauth2) and apply them to appropriate operations using the security field.
- Create Pact consumer contract tests that capture expected interactions from the API consumer perspective, defining expected request/response pairs per endpoint.
- Set up provider verification that replays Pact interactions against the actual API implementation, verifying the provider satisfies all consumer expectations.
- Generate contract artifacts: OpenAPI spec file, Postman collection, and consumer contract (Pact JSON), all versioned alongside the API source code.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/openapi.yaml - Complete OpenAPI 3.0/3.1 specification${CLAUDE_SKILL_DIR}/contracts/pact/ - Consumer-driven contract definitions (Pact JSON)${CLAUDE_SKILL_DIR}/contracts/postman/ - Generated Postman collection for API testing${CLAUDE_SKILL_DIR}/tests/contract/consumer/ - Consumer contract test implementations${CLAUDE_SKILL_DIR}/tests/contract/provider/ - Provider verification test suite${CLAUDE_SKILL_DIR}/scripts/generate-contract.sh - Contract generation automation script
Error Handling
| Error |
Cause |
Solution |
| Spec-code divergence |
API implementation changed without updating the OpenAPI spec |
Add CI check that generates spec from code and diffs against committed spec |
| Pact verification failure |
Provider response does not match consumer expectation |
Review consumer contract for correctness; update provider if contract is valid |
| Missing operation ID |
Endpoint has no operationId, preventing code generation |
Generate deterministic operation IDs from method + path (e.g., getUsers, createUser) |
| Circular schema reference |
Components reference each other creating infinite recursion |
Break cycles with allOf composition or introduce intermediate types |
| Example/schema mismatch |
Example values do not validate against their own schema |
Auto-validate all examples during spec generation; reject mismatched examples |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
Code-first OpenAPI generation: Scan Express route decorators and Zod validation schemas to auto-generate a complete OpenAPI 3.1 spec with accurate request/response schemas, examples, and descriptions.
Consumer-driven contract testing: Frontend team publishes Pact contracts defining the API interactions they depend on; backend CI verifies every contract on each deployment, preventing breaking changes.
Design-first workflow: Author OpenAPI spec in Stoplight Studio, generate server stubs and client SDKs from the spec, then implement business logic in the stubs -- spec stays as the single source of truth.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: jeremylongshore-claude-code-plugins-plus-skills-generati-53description: Generating API Contracts4---5# Generating API Contracts67## Overview89Generate OpenAPI 3.0/3.1 specifications and consumer-driven contract tests from existing API implementations, design documents, or database schemas. Produce machine-readable contracts that serve as the single source of truth for code generation, documentation, testing, and gateway configuration, with Pact integration for consumer-driven contract verification.1011## Prerequisites1213- API implementation with route definitions and handler logic, or design requirements document14- OpenAPI authoring tool: Swagger Editor, Stoplight Studio, or IDE with OpenAPI extension15- Consumer-driven contract framework: Pact (polyglot), Spring Cloud Contract (Java), or Dredd (generic)16- Schema validation tool: Spectral for OpenAPI linting17- Version control for contract files with diff-based review process1819## Instructions20211. Scan existing route handlers and controller files using Grep and Read to extract all endpoint paths, HTTP methods, request parameter names/types, and response body shapes.222. Generate OpenAPI 3.0 specification from the extracted data, including `info` (title, version, description), `servers` (environment URLs), `paths` (operations), and `components` (reusable schemas).233. Define request schemas with field-level constraints: `type`, `format`, `required`, `minimum/maximum`, `pattern` (regex), `enum`, and `example` values for every property.244. Document all response status codes per endpoint with separate schemas: 200/201 for success, 400 for validation errors (with field-level error array), 401/403 for auth failures, and 404/500.255. Add security scheme definitions (`bearerAuth`, `apiKey`, `oauth2`) and apply them to appropriate operations using the `security` field.266. Create Pact consumer contract tests that capture expected interactions from the API consumer perspective, defining expected request/response pairs per endpoint.277. Set up provider verification that replays Pact interactions against the actual API implementation, verifying the provider satisfies all consumer expectations.288. Generate contract artifacts: OpenAPI spec file, Postman collection, and consumer contract (Pact JSON), all versioned alongside the API source code.2930See `${CLAUDE_SKILL_DIR}/references/implementation.md` for the full implementation guide.3132## Output3334- `${CLAUDE_SKILL_DIR}/openapi.yaml` - Complete OpenAPI 3.0/3.1 specification35- `${CLAUDE_SKILL_DIR}/contracts/pact/` - Consumer-driven contract definitions (Pact JSON)36- `${CLAUDE_SKILL_DIR}/contracts/postman/` - Generated Postman collection for API testing37- `${CLAUDE_SKILL_DIR}/tests/contract/consumer/` - Consumer contract test implementations38- `${CLAUDE_SKILL_DIR}/tests/contract/provider/` - Provider verification test suite39- `${CLAUDE_SKILL_DIR}/scripts/generate-contract.sh` - Contract generation automation script4041## Error Handling4243| Error | Cause | Solution |44|-------|-------|----------|45| Spec-code divergence | API implementation changed without updating the OpenAPI spec | Add CI check that generates spec from code and diffs against committed spec |46| Pact verification failure | Provider response does not match consumer expectation | Review consumer contract for correctness; update provider if contract is valid |47| Missing operation ID | Endpoint has no `operationId`, preventing code generation | Generate deterministic operation IDs from method + path (e.g., `getUsers`, `createUser`) |48| Circular schema reference | Components reference each other creating infinite recursion | Break cycles with `allOf` composition or introduce intermediate types |49| Example/schema mismatch | Example values do not validate against their own schema | Auto-validate all examples during spec generation; reject mismatched examples |5051Refer to `${CLAUDE_SKILL_DIR}/references/errors.md` for comprehensive error patterns.5253## Examples5455**Code-first OpenAPI generation**: Scan Express route decorators and Zod validation schemas to auto-generate a complete OpenAPI 3.1 spec with accurate request/response schemas, examples, and descriptions.5657**Consumer-driven contract testing**: Frontend team publishes Pact contracts defining the API interactions they depend on; backend CI verifies every contract on each deployment, preventing breaking changes.5859**Design-first workflow**: Author OpenAPI spec in Stoplight Studio, generate server stubs and client SDKs from the spec, then implement business logic in the stubs -- spec stays as the single source of truth.6061See `${CLAUDE_SKILL_DIR}/references/examples.md` for additional examples.6263## Resources6465- OpenAPI Specification 3.1: https://spec.openapis.org/oas/v3.1.066- Pact contract testing: https://pact.io/67- Swagger Editor: https://editor.swagger.io/68- Dredd API contract testing: https://dredd.org/6970---71> Converted and distributed by [TomeVault](https://tomevault.io/claim/jeremylongshore) — claim your Tome and manage your conversions.72<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io