📜 F1 · What Is an OpenAPI Spec? The Contract Concept

F1 · What Is an OpenAPI Spec? The: An OpenAPI spec (`openapi.yaml`/`.json`) is a building's **architectural blueprint** — the building (the code) already exists and works, but an

An OpenAPI spec (`openapi.yaml`/`.json`) is a building's **architectural blueprint** — the building (the code) already exists and works, but an electrician (another team, a test tool) does not need to walk through every room by hand to understand the building; looking at the blueprint is enough. You saw the "contract" concept in GROUP A (A1) — the OpenAPI spec puts that abstract contract into a **machine-readable, standard format**: which path (`/api/v1/bugs`) accepts which method (GET/POST), which fields are required, what the response looks like — all in ONE file, with no need to read prose. So if the code already exists (a `Controller` class in Java, a DTO in TypeScript), why is a separate spec file needed? Because code is a format only a developer who knows that language can read; the spec is a COMMON language that DOZENS of different tools — Postman, Swagger UI, code generators, contract tests — can read SIMULTANEOUSLY. The closest Java equivalent is an `interface` combined with JavaDoc: the `interface` guarantees the method's SIGNATURE (what it takes, what it returns), the JavaDoc explains it for a HUMAN; an OpenAPI spec does both, for machine and human, in ONE file. For QA, this spec is the fastest way to learn an API's contract without reading code — and as you will see throughout GROUP F, the moment this contract DIVERGES from REALITY is exactly the moment a "contract defect" is born.

/api/v1/bugs — A Minimal Spec

🎬 The Code Exists, but Nobody Has to Read It

Postman / Swagger UI / Tests

Tester learns without reading code

A developer writes the Controller code for `/api/v1/bugs` — the contract is embedded INSIDE the code.

This contract is POURED into `openapi.yaml` — now it is readable without reading code.

Postman, Swagger UI, contract tests — DOZENS of tools can read this ONE file SIMULTANEOUSLY.

The lesson — even without knowing Java/TypeScript, a tester learns what the API accepts and returns by reading the spec.

A Contract's Journey from Source Code to Spec

Controller/DTO classes carry the contract inside the code — but only a developer can read it.

Spec is generated/written…

openapi.yaml pours the same contract into a standard, machine-readable format (you will see auto-generation in F2).

Swagger UI, Postman, and test tools understand the API from the spec, WITHOUT reading code.