# OpenAPI-first workflow

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

```yaml
# .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 } } }
```

```bash
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

```bash
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.
