Validating an API against its OpenAPI spec

Schemas & Contracts

Import an OpenAPI 3.x document, check live responses against it, and catch the drift between what an API promises and what it actually returns.

Updated

An OpenAPI spec is a promise: these endpoints exist, they take these parameters, and they return these shapes. The problem is that the promise is written once and the code changes every week. Validation is how you find out when they stopped agreeing.

What an OpenAPI spec gives you

An OpenAPI 3.x document describes an API in a machine-readable form — every path, method, parameter, and response schema. It is the closest thing most APIs have to a contract, and because it is structured data rather than prose, a tool can act on it: generate requests, generate schemas, and check responses against it.

If the API you are testing publishes one — often at /openapi.json or /swagger.json — you are holding its contract already.

Import the spec

Rather than retyping endpoints by hand, import the document. SchemaClient reads an OpenAPI 3.x file and generates the requests along with the response schemas defined in it. What was a wall of documentation becomes a ready-to-send collection.

Validate live responses

Now send a request and check the response against the schema the spec declared. You get one of two outcomes:

  • It matches. The endpoint does what its documentation says.
  • It diverges. You get a list of exactly which fields differ, and how — a renamed key, a number returned as a string, a field the spec marks required that came back missing.

That list is the whole value. It tells you whether the server drifted from the contract or the contract was wrong to begin with.

Where specs and reality diverge

The mismatches that show up most often are quiet ones a status-code check never catches:

  • A field documented as required is sometimes absent.
  • A field documented as non-nullable comes back null.
  • An enum gained a value the spec does not list.
  • A timestamp changed format between two "compatible" releases.

Every one of these ships a 200 OK. Every one breaks a consumer that trusted the spec. This is the same trap covered in why a 200 OK response can still be broken — the spec just gives you something precise to check against.

Make it part of the workflow

Validation earns the most when it is not a one-off. Two habits pay back quickly:

  • Before you integrate a third-party API, validate its live endpoints against its published spec. You will usually find at least one divergence, and it is far cheaper to find it now than in production.
  • Before you release your own API, validate it against the spec you publish, so a serializer change does not ship a breaking rename to mobile clients that cannot be force-updated.

The mechanics are the same either way, and they build directly on validating API responses against a schema — importing the spec just saves you writing the schema by hand.

Frequently asked questions

What is the difference between OpenAPI and Swagger?

They are the same lineage. Swagger was the original name; from version 3.0 the specification was renamed OpenAPI, and Swagger now refers to the tooling built around it. An OpenAPI 3.x document and a Swagger 3.x document are the same thing.

Can I generate requests from an OpenAPI spec?

Yes. Importing an OpenAPI 3.x document into SchemaClient generates the requests and their response schemas in one step, so you do not retype a contract the API already publishes.

Why validate against the spec if the API already follows it?

Because the two drift. Specs are written once and edited rarely; the code changes every sprint. Validating the live endpoint against its own document is often the fastest way to prove the documentation is now wrong.