| name | openapi-spec |
| description | 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`. |
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.
