Should I author the OpenAPI spec first or generate it from my code?

Short answer: your real problem isn’t “spec-first vs code-first” — it’s the drift itself. Whichever direction you pick, the two will keep diverging unless you validate the spec against the code in CI. The direction is a preference; the validation is mandatory.

1. What actually differs. Code-first (Scramble, L5-Swagger) generates the schema from your controllers and annotations; it stays faithful to the implementation but buries the design in code, makes review harder, and accumulates annotation noise. Contract-first means you write openapi.yaml first and make the code conform; it forces the design conversation up front but demands discipline.
2. The only thing that ends drift is validation. Regardless of direction, without a contract test the published schema and the real response will drift again. Your tickets come from exactly that gap — nobody can keep them in sync by hand forever.
3. If you have partners, go contract-first. You publish the contract first; partners build against a mock server like Prism without waiting on you, and you lock the implementation to the contract. The design debate ends before it hits the code.
4. Bind Laravel to the spec. Keep openapi.yaml in the repo, lint it with Spectral in the PR, and use Spectator to assert every endpoint’s real response against the schema:

$this->getJson('/api/orders/42')
    ->assertValidResponse(200); // validated against openapi.yaml

5. Pick a single source of truth. Let openapi.yaml be the one truth; your published docs and the clients partners generate should both be derived from it in CI. If you have two sources, drift is guaranteed.
6. Accept the cost. Contract-first has a learning curve and YAML discipline; code-first starts fast but leaves design review weak. The decision really comes down to whether your team is mature enough to maintain the contract by hand.

Bottom line: personally I’d go contract-first: openapi.yaml as the SSOT, Spectral lint in the PR, Spectator request/response validation in tests, and docs plus partner clients generated from that file in CI. What matters isn’t the direction — it’s that green contract test. The moment you push drift detection into the pipeline instead of leaving it to code review, the tickets stop.