One Source of Truth for Requirements, Code, Documentation, and Tests

Software teams don't usually fail because individuals do bad work. They fail because the work doesn't stay in sync. A product manager writes acceptance criteria in a ticket. A backend engineer implements against their interpretation of it. A frontend team builds to a Postman collection that drifted from the real API weeks ago. A QA engineer writes tests against behavior that was changed in a meeting nobody documented. By the time something ships, four teams have four versions of the truth — and the API is a fifth. This tutorial is about eliminating that gap at its source. The central argument is simple: an OpenAPI description, written carefully, is the acceptance criteria. An Arazzo workflow document is the user journey spec. A Schemathesis test run is the QA sign-off. A PHPUnit test suite is the living proof that the implementation honors the contract. When product, frontend, backend, and QA all work from the same machine-readable artifact, synchronization stops being a communication problem and becomes a tooling problem — one with tractable solutions. We open by establishing OpenAPI as a shared contract, not a documentation afterthought. Attendees will learn to write descriptions that encode acceptance criteria precisely enough that product managers can review them, backend engineers can implement against them, frontend engineers can mock from them on day one, and QA engineers can derive test cases from them automatically. One file. Four audiences. No translation layer. We then introduce Arazzo to capture what OpenAPI alone cannot: the sequences, dependencies, and conditional flows that define how real users move through an API. Multi-step scenarios — authentication, onboarding, checkout, error recovery — become versioned, reviewable workflow documents that product and engineering sign off on together, rather than living in someone's head or buried in a Confluence page nobody updates. Finally, we wire both specifications into Schemathesis, demonstrating how a spec that product and engineering already agreed on becomes a test suite that runs in CI without QA having to write it from scratch. Failures surface as violations of the shared contract, not as ambiguous bug reports — making it immediately clear whether the issue is in the implementation, the spec, or the original requirement. Throughout, the tutorial treats the specification not as a technical artifact owned by engineers, but as the single surface where every role's concerns are expressed, negotiated, and verified. Attendees will leave with concrete workflows for keeping product tickets, API descriptions, mock servers, implementation, and test suites pointing at the same truth — and for making drift visible the moment it appears, rather than three weeks after a release. Target audience: Anyone who has ever been in a meeting where product, frontend, backend, and QA all had different answers to the question "what is this API supposed to do?" No prior OpenAPI experience is required.

Comments

Comments are closed.