Treating OpenAPI specs as build artifacts: a working pattern in Laravel with accord, forge, and drift.

You ship a Laravel API. You publish OpenAPI docs. The two are correct on the day you launch.

Three months later they aren't.

Maybe a nullable slipped into a response field and the iOS client started crashing on null pointer dereferences. Maybe a field got renamed in v1.2 and a partner integration silently broke for two weeks. Maybe an entire endpoint got added without a spec entry, and the docs page lies to every new developer who reads it.

The spec didn't lie when it was written. It just stopped being true.

The cost of catching that drift scales with how late you catch it: cheap in your editor, manageable in CI, expensive in staging, ruinous in production. The longer the contract goes unverified, the more confidently your team builds on top of a fiction.

The good news is that a contract is just a spec file. It can be checked. It can be a CI gate. The version of this checking that I've found practical is what this post is about.

What "API contract adherence" actually means

Two specific guarantees:

1. Implementation matches spec. Every route the application actually serves is described by the spec. Every request and response shape that goes over the wire conforms to the schemas in the spec.
2. Spec matches implementation. No spec entries describe routes the application no longer serves. No schemas in the spec describe shapes the application no longer produces. Both directions matter. If your spec says "/users supports DELETE" and your code removed DELETE last sprint, clients are going to call DELETE and you're going to wonder why they're seeing 405s.

OpenAPI 3.0 is the standard format for writing this contract down. It's a YAML or JSON document describing paths, operations, parameters, request bodies, and response shapes. The format is mature enough that I'm going to skip describing it in this post. If you're working on a JSON HTTP API, you've seen OpenAPI before; if you haven't, the spec docs are short.

The interesting question isn't "what does OpenAPI look like." The interesting question is: how do you keep your spec honest?

Three classes of drift

When your spec and your implementation get out of sync, the drift falls into roughly three buckets.

Structural drift. Routes added, removed, or moved. The spec says /v1/posts exists; your code doesn't have it. Or your code has /v1/posts/{id}/restore; the spec doesn't.

Shape drift. Request or response bodies that no longer match the schema. The spec says name is required and a string; your code is now accepting an array, or making it optional, or removing the field entirely.

Semantic drift. The route exists and the shape matches, but the meaning has changed. Same field name, different units. Same status code, different conditions for returning it. This is the hardest class to catch programmatically and the most expensive when it happens.

The first two classes are mechanizable. The third is mostly about reviewer discipline. The pattern I'll describe handles the first two well enough that the third is the only thing humans still need to look for.

Contract adherence as a CI/CD gate

The pattern I want to talk about is treating contract adherence as a build gate. Not a soft expectation, not a documentation chore, but a hard CI check that exits non-zero when violated.

This is more useful than runtime-only validation, for one reason: by the time a contract violation hits production, the cost is already incurred. Catching it at build time means the version of the code that violates the contract literally cannot merge. The drift doesn't ship.

A CI gate has three components:

1. A spec file that's authoritative (committed to the repo, reviewed in PRs, treated as code).
2. A runtime validator that checks live requests and responses against the spec.
3. A drift detector that runs in CI, compares the routes the app actually exposes against the routes the spec describes, and fails the build on mismatch. You can build this yourself. You can also use existing tools. I built and maintain the toolchain I'm about to describe because the existing PHP options either didn't enforce both directions, didn't support multiple frameworks, or were heavy enough that adoption was a project unto itself.

The working pattern, in Laravel

The toolchain is called accord, and it's the foundation of a small family of Fissible packages that together cover the spec → validate → drift loop:

• fissible/forge scaffolds an OpenAPI spec from your existing routes.
• fissible/accord validates live traffic against the spec at runtime.
• fissible/drift detects drift between routes and spec, and fails CI when it happens. Each piece is independently useful, and they snap together into the CI/CD gate.

Step 1: get a spec, even if it's empty

If your API has been running without a spec, the cheapest first step is to scaffold one from your existing routes:

composer require --dev fissible/forge
php artisan accord:generate --title="My API"

forge walks your registered routes, infers request body schemas from your Laravel FormRequest classes, and writes a starting resources/openapi/v1.yaml with every endpoint accounted for. Response schemas are scaffolded as empty objects, and those are the ones you fill in to describe what your API actually returns.

The FormRequest inference is the one piece of forge that I want to call out. Laravel's validation rules are already a declarative description of an input contract, so lifting them into an OpenAPI request schema is mostly a translation problem rather than a generation problem. If your codebase uses FormRequest classes in a disciplined way, you get half of the spec for free.

Step 2: turn on runtime validation in log mode

Install accord and register the middleware:

composer require fissible/accord

// bootstrap/app.php (Laravel 11+)
use Fissible\Accord\Drivers\Laravel\Http\Middleware\ValidateApiContract;

->withMiddleware(function (Middleware $middleware) {
    $middleware->appendToGroup('api', ValidateApiContract::class);
})

Configure log mode initially:

ACCORD_FAILURE_MODE=log

Log mode is the adoption trick. In log mode, accord still validates every request and response, but instead of throwing on violations it logs PSR-3 warnings and lets the request through. Your application keeps working, your logs start filling up with concrete violations, and you have a list of things to fix in your spec or your code before flipping to exception mode.

Without this mode, adopting accord on a live API is a "stop everything" project. With it, adoption is "run it for a week, fix what surfaces, then flip the switch."

Step 3: add the CI gate

Once you trust the spec, add drift's accord:validate command to CI:

- name: Check API contract (drift)
  run: php artisan accord:validate

- name: Check implementation coverage
  run: php artisan drift:coverage

accord:validate exits non-zero if the spec and the implementation have drifted in either direction. drift:coverage is an optional second check that catches routes that exist in the codebase but are wired to nothing (skeleton routes, a real production hazard).

With this gate in place, the only way to merge a route change is to update the spec to match. The spec stops being a documentation artifact and becomes part of the codebase under the same review discipline as any other change.

What's technically interesting under the hood

Most of what makes accord work is unglamorous: parse the OpenAPI document, build a route lookup, hand each request through a validator that knows about JSON schemas. Three pieces are worth pulling out.

PSR-7/15 core, framework drivers

The validator and middleware in src/ have no Laravel dependency, no Slim dependency, no Mezzio dependency. Framework integration lives entirely in src/Drivers/{Framework}/. The Laravel driver is a thin service provider plus a middleware wrapper that adapts Laravel's request/response objects into PSR-7 messages.

The boundary is enforced architecturally: anything outside src/Drivers/ is forbidden from importing framework-specific code. Adding a new framework driver is implementing DriverInterface and writing a glue middleware. The cleanliness of this boundary is the kind of thing that doesn't matter the day you build it and matters every day after.

FailureMode as an enum, not a flag

I wanted three behaviours for contract violations: throw, log, or hand the result to a user-provided callable. The naive way is to thread booleans and special config values through the validator. The honest way is a single enum:

enum FailureMode: string
{
    case Exception = 'exception';
    case Log       = 'log';
    case Callable  = 'callable';
}

The validator produces an immutable ValidationResult:

final class ValidationResult
{
    private function __construct(
        public readonly bool $valid,
        public readonly string $version,
        public readonly array $errors = [],
    ) {}

    public static function valid(string $version): self    { /* ... */ }
    public static function invalid(array $errors, string $version): self { /* ... */ }
}

The failure mode decides what to do with the result. The benefit shows up when you go to extend: adding a fourth behaviour (queued reporting, for example) is a new enum case and a new branch, not a new flag and a new conditional everywhere.

Pluggable spec sources

A spec doesn't have to be a local file. The SpecSourceInterface abstraction lets accord load specs from anywhere:

interface SpecSourceInterface
{
    public function load(string $version): ?OpenApi;
    public function exists(string $version): bool;
}

The default file source loads YAML or JSON from disk. A URL source fetches from a remote endpoint with optional PSR-16 caching, which is useful when multiple services validate against a shared central spec. A custom source lets you load specs from a database, a registry, or a tenant-specific lookup in a multi-tenant API. The interface is intentionally small: two methods, and you can validate against specs from anywhere.

Where this fits in Fissible's larger picture

I run a company called Fissible and build a product called Station, a self-hosted Laravel CMS and workflow platform. Station ships with a Platform Core that lets focused modules (CMS, Flow, Forms, an API module, more on the way) dock in and share auth, navigation, search, and admin UI.

The API module is where accord becomes load-bearing. Station's API surface is contract-validated end to end: forge scaffolds the spec from the routes the modules expose, accord validates live traffic, drift fails CI when the spec and the implementation diverge. Treating the contract as code isn't an aspirational team policy in Station. It's mechanically enforced.

If you want to see this pattern running end-to-end on a real product, Station is where to look. If you just want the validator and the CI gate for your own Laravel API, accord and drift are the two packages to install.

The short version

API contract adherence is a CI/CD problem more than a documentation problem. You write the contract once. You validate against it at runtime. You fail the build when it drifts. After that, the spec is honest because the build won't pass otherwise, and the cost of a contract violation collapses from "found in production" to "found in the PR that introduced it."

The earlier a breach is caught, the cheaper it is to fix. Treating the spec as a build gate makes catching it the default.