agentsclimarketplace

Openapi contracts

Skill Amey-Thakur/AI-SKILLS/skills/apis/openapi-contracts

Plug-and-play skills and prompts for every AI coding agent

Install
npx -y skills add Amey-Thakur/AI-SKILLS --skill openapi-contracts

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 18 days oldThe repository was created 18 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
  • 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

3.7 KB, as published. Nobody here has run it

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.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.