Org Skills
Referenceapi-design

OpenAPI-first workflow

Supporting material for api-design. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified 2026-09 against https://spec.openapis.org/oas/latest.html (v3.2.1, 10 September 2026), https://docs.stoplight.io/docs/spectral and https://github.com/oasdiff/oasdiff.

1. The loop

  1. Change the document first. The OpenAPI file is reviewed in the pull request like code, before the handler exists. A contract argued about after the code is written is a contract nobody changes.
  2. Lint it with Spectral, using the base spectral:oas ruleset plus house rules (§3).
  3. Diff it against the published version with oasdiff and fail the build on a breaking change that has no version bump.
  4. Generate what you can — clients, server stubs, mock servers, documentation — from the one file.
  5. Publish it as a build artefact, so "the spec" is never someone's local copy.

2. 3.1 or 3.2?

OpenAPI 3.1 OpenAPI 3.2.1
Released 2021, universally supported September 2026
JSON Schema Full JSON Schema 2020-12 Same
Tooling Every generator, linter and documentation tool Catching up; check each tool you depend on
ASP.NET Core 10 Emits 3.1 by default Configurable

Default to 3.1. Move to 3.2 when your linter, your generator and your documentation renderer all support it, and say so in the ADR — a document your pipeline cannot parse is worse than an older version of the same information.

3. A house Spectral ruleset

# .spectral.yaml
extends: ["spectral:oas"]

rules:
  operation-operationId: error
  operation-tags: error

  all-operations-secured:
    description: Every operation declares a security requirement (use [] for public ones).
    severity: error
    given: $.paths[*][get,put,post,delete,patch]
    then:
      field: security
      function: truthy

  errors-are-problem-json:
    description: 4xx and 5xx responses use application/problem+json (RFC 9457).
    severity: error
    given: $.paths[*][*].responses[?(@property.match(/^[45]/))].content
    then:
      field: application/problem+json
      function: truthy

  collections-are-paginated:
    description: A list operation must accept a limit parameter.
    severity: warn
    given: $.paths[?(@property.match(/^\/[a-z-]+$/))].get.parameters
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          contains: { type: object, properties: { name: { const: limit } } }
npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=warn

Three rules cover most real review comments: every operation is secured, every error is problem+json, every collection is bounded. Add house rules only for things you have actually had to say twice — a ruleset with forty rules gets disabled wholesale the first time it blocks a release.

4. Breaking-change detection

oasdiff breaking https://api.example.com/openapi.yaml ./openapi.yaml --fail-on ERR

Run it against the published document, not against main, so a breaking change merged last week is still caught today. What it catches that review misses: a response field becoming optional, an enum losing a value, a parameter becoming required, a format change, a status code disappearing.

When a break is intentional, the same pull request carries the version bump and the deprecation headers. A suppression with no version bump is how a client finds out in production.

5. Generation, and what not to generate

Generate Why
Clients for internal consumers Free, always in step with the contract
Mock server (Prism, or the spec's examples) Consumers start before the provider exists
Documentation (Redocly, Scalar, Swagger UI) One source, never a stale wiki page
Request validation middleware The document becomes executable, so drift is impossible

Server stubs are the doubtful one: generated handler skeletons rot the moment anyone edits them, and regenerating means a merge. Generating request validation from the document and writing the handlers by hand gives you the enforcement without the merge.

Where the code is the source of truth instead (attribute-driven generation in ASP.NET Core, schema- driven in Fastify), the workflow still works: generate the document in the build, commit or publish it, and run the same lint and diff steps. What matters is that a human reviews the document in the pull request — not which side produced it.

6. Owning the error catalogue

type URIs in problem+json are part of the contract: a client branches on them and they can never change. Give them an owner and a home.

  • One registry file listing every type, its meaning, its status code and whether it is retryable.
  • The URI resolves to human-readable documentation. It need not, but a type that 404s trains everyone to ignore them.
  • Adding a type is additive and safe. Changing what one means is breaking, even though no schema changed — which is exactly why it needs a registry rather than a string literal in a handler.
  • Namespace them per service or module (https://api.example.com/problems/orders/already-shipped) so two teams cannot collide.