Agent skill · software engineering · jeremylongshore
generating-api-contracts
Generate API contracts and OpenAPI specifications from code or design
Why this skill is useful
Adds an executable script for generating OpenAPI specifications and consumer-driven contract tests that automate API documentation and verification processes.
What it needs
Requires bash, grep installed locally. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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 1. 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. 2. Generate OpenAPI 3.0 specification from the extracted data, including info (title, version, description), servers (environment URLs), paths (operations), and components (reusable schemas). 3. Define request schemas with field-level constraints: type, format, required, minimum/maximum, pattern (regex), enum, and example values for every property. 4. 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. 5. Add security scheme definitions (bearerAuth, apiKey, oauth2) and apply them to appropriate operations using the security field. 6. Create Pact consumer contract tests that capture expected interactions from the API consumer perspective, defining expected request/response pairs per endpoint. 7. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/generating-api-contracts