Generate API contracts and OpenAPI specifications from code or design documents. Use when documenting API contracts and specifications. Trigger with phrases like "generate API contract", "create OpenAPI spec", or "document API contract".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill generating-api-contractsLoading…
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.
info (title, version, description), servers (environment URLs), paths (operations), and components (reusable schemas).type, , , , (regex), , and values for every property.formatrequiredminimum/maximumpatternenumexamplebearerAuth, apiKey, oauth2) and apply them to appropriate operations using the security field.See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
${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 | 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.
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.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.