ReferenceBeginner4-6 min reference
OpenAPI / Swagger
An OpenAPI document (formerly "Swagger") is a machine-readable description of an API — paths, parameters, schemas, and responses. For QA it's a free test oracle: every required field, enum, and status code is the spec you assert against. This is a lookup of the structure and what to check; for schema-assertion mechanics see the API Schema Validation sheet linked below.
Document structure
| Key | Holds |
|---|---|
openapi | Spec version (e.g. 3.1.0) |
info | Title, version of the API |
servers | Base URLs per environment |
paths | Endpoints → operations (get, post, …) |
components.schemas | Reusable data models |
components.securitySchemes | Auth (bearer, OAuth2, apiKey) |
Inside an operation
| Field | What QA reads from it |
|---|---|
parameters | path/query/header params, required, types |
requestBody | payload schema + required fields |
responses | every documented status code + body schema |
required | fields that must be present (negative tests) |
enum | the only allowed values (boundary tests) |
format | date-time, email, uuid — validation rules |
deprecated | flag if still in use |
What QA verifies against the spec
- Every documented status code is reachable (200, 201, 400, 401, 404, 422…).
- Responses match the declared schema — no extra/missing fields, correct types.
requiredrequest fields actually rejected when omitted (→ 400/422).enumvalues accepted; out-of-enum rejected.- The implementation hasn't drifted from the spec (a common bug source).
Common mistakes
- Trusting the spec as truth — it can be out of date; test that code matches it.
- Ignoring
2.0(Swagger) vs3.xdifferences (definitionsvscomponents.schemas). - Testing only documented happy responses, never the documented error codes.
- Not regenerating the spec in CI, so drift goes unnoticed.
// Related resources