openapi-contracts
/openapi-contracts
Drive API development from an OpenAPI spec as the contract, with linting, codegen, and drift detection. Use when building or documenting REST APIs and wanting the spec to be the single source of truth.
- Author
- Amey-Thakur ↗
- Repository
- AI-SKILLS ↗
- Licence
- MIT
- Last repository change
- 05.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Drive API development from an OpenAPI spec as the contract, with linting, codegen, and drift detection. Use when building or documenting REST APIs and wanting the spec to be the single source of truth.
Original author description
Drive API development from an OpenAPI spec as the contract, with linting, codegen, and drift detection. Use when building or documenting REST APIs and wanting the spec to be the single source of truth.
How it works
- Method
- Boundaries
SKILL.md preview
--- name: openapi-contracts description: Drive API development from an OpenAPI spec as the contract, with linting, codegen, and drift detection. Use when building or documenting REST APIs and wanting the spec to be the single source of truth. --- # OpenAPI contracts An OpenAPI spec can be the single source of truth for a REST API: documentation, client and server code, mocks, and tests all derived from it. The value comes from making the spec the *contract* everything else is generated from or checked against, not a document written after the fact and immediately stale. ## Method 1. **Design spec-first for new APIs.** Write the OpenAPI spec before implementing: it forces the interface decisions (resources, methods, schemas, errors: see rest-endpoint-design, api-error-responses) up front, enables parallel work (frontend against a mock, backend against the contract), and produces the documentation for free. Code-first (annotations generating the spec) is viable for existing APIs but tends toward implementation-shaped rather than consumer-shaped design. 2. **Lint the spec for consistency.** A spec linter (Spectral-class) enforces naming conventions, required descriptions, error-response coverage, and org-wide rules (see style-guides for the API): so every endpoint across the org is consistent and documented, caught at spec-review not after shipping. An unlinted spec drifts into inconsistency endpoint by endpoint. 3. **Generate clients and server stubs from the spec.** Client SDKs (see api-sdk-design), server request/response models, and validation from the one spec: so the code cannot diverge from the contract, and consumers get typed clients without hand-writing them. This is the payoff of spec-first: the contract is executable, not aspirational. 4. **Validate requests and responses against the spec at runtime.** Middleware that checks incoming requests and outgoing responses conform to the spec (in test/staging at least): catches the drift where the implementation quietly stops matching the contract (a field added in code but not the spec, or vice versa: see request-validation). Contract and implementation staying in sync is the whole point; verify it, do not assume it. 5. **Detect drift in CI.** Compare the spec against the actual API behavior (contract tests: see contract-testing) and fail the build on divergence; diff spec changes in PRs to catch breaking changes (see api-change-management: a removed field or tightened type in the spec is a breaking change flagged at review). The spec is only a source of truth if drift from it is caught. 6. **Serve the spec as living documentation.** Interactive docs (Swagger UI / Redoc) generated from the spec, always matching the real API because it is the same artifact (see api-reference-docs, docs-as-code): consumers explore and try endpoints against accurate, current documentation instead of a hand-written page that lies. ## Boundaries - Spec-first requires discipline (writing and reviewing the spec before coding); for a quick internal API with one consumer it can be overhead, and code-first with generated docs suffices. Match the ceremony to the API's reach and consumer count. - The spec captures structure (endpoints, schemas, types), not all behavior (business rules, side effects, ordering guarantees); those still need prose and examples (see api-reference-docs). The spec is necessary, not sufficient, documentation. - GraphQL and gRPC have their own contract mechanisms (SDL, proto: see graphql-schema-design, grpc-services); OpenAPI is the REST tool. The contract-first principle transfers across all three.
Versions
The database has no other skills named openapi-contracts.
Database snapshot: 13.11.2026 · package version c4babcff088e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100generating-api-contracts
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". - 100generating-api-contracts
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". - 100go-openapi
Spec-first REST development in Go with OpenAPI: generating server interfaces and clients with oapi-codegen, request validation middleware, RFC 9457 error bodies, contract testing, and detecting breaking API changes. Use when the API has or should have an OpenAPI document, when… - 100openapi-spec-generator
Generate openapi spec generator operations. Auto-activating skill for API Development. Triggers on: openapi spec generator, openapi spec generator Part of the API Development skill category. Use when working with APIs or building integrations. Trigger with phrases like "openapi… - 90backend-openapi-documentation
Use this skill when the user says 'OpenAPI', 'Swagger', 'API documentation', 'spec-first', 'API spec', 'openapi.yaml', 'swagger.json', 'codegen', 'openapi-generator', 'API contract first'. This skill enforces spec-first API documentation with OpenAPI 3.x, code generation, and… - 100openapi-specification
OpenAPI 3.x specification design, schema patterns, and validation for REST API contracts. Use when creating or maintaining API specifications, generating documentation, or validating API contracts.