How do I validate an OpenAPI spec against real API behavior?

To validate an OpenAPI spec against real API behavior, you generally want to compare what the spec says with what the server actually returns for representative requests.

Practical approach

1) Validate the spec itself

First make sure the OpenAPI document is structurally valid:

• Use a linter/validator like:
  • Spectral
  • Swagger CLI
  • openapi-cli
• This catches schema and formatting issues, but not runtime mismatches.

2) Test real requests against the API

Send requests to the live API and compare responses with the spec:

• status codes
• response headers
• response body schema
• required/optional fields
• enum values
• content types
• pagination, auth, error responses

3) Use contract testing tools

These tools automate matching observed behavior to the OpenAPI contract:

• Schemathesis — generates test cases from OpenAPI and checks responses
• Dredd — runs contract tests against an API implementation
• Prism — can mock from OpenAPI, useful for comparing expected vs actual
• Postman/Newman — if you already have collections and examples

4) Compare against examples

If your spec has example or examples, replay those requests and verify:

• response matches schema
• response fields and types match
• errors behave as documented

5) Validate negative cases too

Check how the API behaves when:

• required fields are missing
• invalid enum values are sent
• malformed JSON is sent
• unauthorized requests are made
• unsupported content types are used

This helps ensure the spec includes realistic error behavior.

Recommended workflow

1. Lint the OpenAPI file
2. Generate tests from the spec
3. Run them against staging or a test environment
4. Inspect mismatches
5. Update either the spec or the API implementation
6. Automate in CI

Example with Schemathesis

schemathesis run https://api.example.com/openapi.json --base-url https://staging.api.example.com

This will:

• read the OpenAPI spec
• generate test cases
• send requests to the real API
• report schema/behavior mismatches

What to look for in mismatches

Common issues:

• API returns 200 but spec says 201
• response field is nullable in practice but not in spec
• actual body has extra/missing fields
• response uses text/plain but spec says application/json
• error responses don’t match documented schema

Best practice

Treat the OpenAPI spec as a contract and run contract tests in CI against a staging environment. That gives you early warning when implementation and documentation drift apart.

If you want, I can also show:

• a tool-by-tool comparison
• a CI pipeline example
• or a minimal Schemathesis/Dredd setup.