Openapi spec

Skill amjadjibon/skills/skills/misc/openapi-spec

Write and validate OpenAPI 3.1 spec documents (no code generation) — $ref-based components, Spectral/Redocly lint rules. Trigger on "write an OpenAPI spec", "generate a Swagger doc", "validate my openapi.yaml", or editing a spec file. Shape or versioning not decided yet? Use `dev-api-design`.From its SKILL.md

Install

npx -y skills add amjadjibon/skills --skill openapi-spec

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

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
2 stars2 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.

SKILL.md

3.2 KB, as published. Nobody here has run it

OpenAPI Spec Generation

Patterns for writing OpenAPI 3.1 specs as a design artifact — the contract for an API, not code, and not generated from code. Write it by hand, keep it internally consistent, validate it.

When to Use

Designing an API contract before (or instead of) implementation
Documenting an existing REST API by hand
Reviewing a spec for consistency, missing error responses, or naming drift
Validating a spec against style/lint rules

Assumes the resource shape and design decisions (REST vs. GraphQL, versioning strategy, pagination style) are already made — if they aren't, use dev-api-design first, then come back here to encode the result.

3.1 Structure Baseline

openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  parameters: ...
  responses: ...
  securitySchemes: ...

3.1 is JSON Schema-aligned (unlike 3.0) — nullable is gone in favor of type: [string, "null"], and examples can be an array on any schema, not just a single example. Don't write 3.0-style nullable: true into a 3.1 doc.

A full annotated skeleton (paths, reusable schemas/parameters/responses, security schemes) is in references/details.md — read it before hand-writing a component from scratch.

Rules

Reuse via $ref. A schema, parameter, or response used more than once goes in components/ and gets referenced — never copy-pasted across paths. Duplication here is what makes specs rot.
Every response needs a schema, including errors. List every status code the endpoint can actually return, not just 200/201 — 400/401/403/404/409/422/500 as applicable, each with its real error shape.
Security is explicit per operation. Define every scheme used in components/securitySchemes, and set security: on each operation (or globally with per-operation overrides for public endpoints) — don't leave it implied.
Examples are real values, not "string" or "foo". A consumer copies the example to make their first request; a placeholder value makes that request fail.
Version the API, not just the spec — in the URL path or a header, and bump info.version with semver when the contract changes.
Consistent naming. Pick one casing convention (usually camelCase for JSON properties, kebab-case for paths) and hold it across every path and schema.
No hardcoded environment URLs — use servers: entries (and server variables for path segments like region/tenant) instead of baking a single host into the doc.

Validating

Lint the spec before trusting it — Spectral (spectral lint openapi.yaml) or Redocly (redocly lint openapi.yaml) catch missing descriptions, inconsistent naming, undocumented error responses, and security gaps that manual review misses. Rule-set starting points are in references/details.md.