How do I test API responses against an OpenAPI spec?

You can test API responses against an OpenAPI spec by validating the HTTP response body, headers, and status code against the schema defined in the spec.

Common ways to do it

1) Use a test framework + OpenAPI validator

Typical flow:

1. Send a request to your API.
2. Capture the response.
3. Load your OpenAPI document.
4. Validate the response against the matching operation and status code.

Examples of tools/libraries:

• JavaScript/TypeScript
  • jest + openapi-response-validator
  • openapi-backend
  • ajv with schemas extracted from OpenAPI
• Python
  • prance
  • openapi-core
  • schemathesis
• CLI / contract testing
  • schemathesis
  • dredd
  • openapi-enforcer
• Java
  • rest-assured + schema validation
  • openapi4j

---

2) Validate with a dedicated OpenAPI testing tool

Schemathesis

Good for both testing and property-based fuzzing.

Example:

schemathesis run https://api.example.com/openapi.json

It can:

• generate test cases from your spec
• send requests
• validate responses
• check status codes and schemas

Dredd

Useful for contract testing against a live API.

dredd openapi.yaml https://api.example.com

---

3) Manual validation in tests

If you want more control, your test can explicitly compare the response to the spec.

Example in JavaScript

import fs from 'fs';
import YAML from 'yaml';
import OpenAPIResponseValidator from 'openapi-response-validator';
import fetch from 'node-fetch';

const spec = YAML.parse(fs.readFileSync('./openapi.yaml', 'utf8'));
const validator = new OpenAPIResponseValidator({
  responses: spec.paths['/users/{id}'].get.responses,
  components: spec.components,
});

const res = await fetch('https://api.example.com/users/123');
const body = await res.json();

const validationError = validator.validateResponse(res.status, body, res.headers);
if (validationError) {
  throw new Error(JSON.stringify(validationError, null, 2));
}

---

What to validate

At minimum:

• HTTP status code
• Response body schema
• Content-Type
• Optionally:
  • response headers
  • nullable/required fields
  • enums
  • array item types
  • examples

---

Tips

• Make sure you validate the response against the specific operation and status code in the spec.
• If your spec uses $ref, ensure your validator resolves references.
• Be careful with additionalProperties if you want strict matching.
• Decide whether your tests should be:
  • strict: fail on extra fields
  • lenient: allow extra fields, only enforce required ones

---

Recommended approach

• For automated contract tests, use Schemathesis or Dredd
• For unit/integration tests, use a language-native validator in your test suite
• For CI checks, run a validator against your staging API before release

If you want, I can show you:

1. a JavaScript/Jest example,
2. a Python/pytest example, or
3. a CI pipeline example.