Describing an interface formally.
WHAT IT IS
A standard format describing endpoints, parameters, schemas and responses.
WHAT IT ENABLES
Documentation generated automatically Client libraries generated Validation of requests and responses Mock servers for callers to develop against Contract testing
WHAT TO DEFINE
Every path and method Parameters, with types and whether required Request bodies, with schemas Every response, including errors Security requirements
WHY DEFINING ERRORS MATTERS
They are the part most often undocumented and most often needed.
WHAT DESIGN-FIRST MEANS
Writing the specification before the code.
WHAT IT PROVIDES
Agreement before implementation Callers able to start immediately, against mocks
WHAT CODE-FIRST MEANS
Generating the specification from the implementation.
WHAT IT PROVIDES
A specification that cannot drift.
WHAT IT COSTS
The design emerges from the code rather than being decided.
WHAT TO DO EITHER WAY
Verify the specification against actual behaviour automatically.
WHAT TO REUSE
Schemas, defined once and referenced.
WHY
It keeps definitions consistent and the document manageable.
WHAT TO VERSION
The specification, alongside the code.
WHAT TO PUBLISH
The specification itself, so callers can generate their own tooling.
