Skip to content
Skills Library
Programming · Building & coding

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.

Repository
AI-SKILLS ↗
Licence
MIT
Last repository change
05.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.09.2026, without references to retired models or APIs.

Licence

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

  1. Method
  2. Boundaries
Original SKILL.md headings · 72 lines, 496 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.