What Is OpenAPI?

OpenAPI Specification (formerly known as Swagger) is a standard format for describing REST APIs. It defines every aspect of an API in a machine-readable document: endpoints, HTTP methods, request parameters, response formats, authentication, and data models.

An OpenAPI spec serves as a contract between API providers and consumers. As a tester, it is your source of truth for what the API should do.

OpenAPI vs. Swagger

  • Swagger was the original name, created by SmartBear
  • OpenAPI became the standard name after the specification was donated to the Linux Foundation
  • Swagger UI and Swagger Editor are tools that work with OpenAPI specs
  • Current version: OpenAPI 3.1 (aligned with JSON Schema)

Reading an OpenAPI Specification

OpenAPI specs are written in YAML or JSON. Here’s a simplified example:

openapi: 3.1.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: User created
        '400':
          description: Validation error

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: integer
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, viewer]
        createdAt:
          type: string
          format: date-time

    CreateUser:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, viewer]
          default: user

Key Sections

SectionPurpose
infoAPI title, version, description
serversBase URLs for different environments
pathsEndpoints with methods and parameters
components/schemasReusable data models
securityAuthentication requirements

JSON Schema Fundamentals

JSON Schema defines the structure and validation rules for JSON data. OpenAPI uses JSON Schema for request and response bodies.

Common Types and Constraints 

# String with constraints
name:
  type: string
  minLength: 1
  maxLength: 255
  pattern: "^[A-Za-z ]+$"

# Number with range
age:
  type: integer
  minimum: 0
  maximum: 150

# Enum (allowed values)
status:
  type: string
  enum: [active, inactive, suspended]

# Array with item type
tags:
  type: array
  items:
    type: string
  minItems: 1
  maxItems: 10
  uniqueItems: true

# Nullable field
deletedAt:
  type: ["string", "null"]
  format: date-time

Test Cases from Schema

Every schema constraint generates test cases:

Schema RulePositive TestNegative Test
required: [name]Include name fieldOmit name field
minLength: 1Send "A"Send "" (empty)
maxLength: 100Send 100 charsSend 101 chars
minimum: 0Send 0Send -1
enum: [a, b, c]Send "a"Send "d"
type: integerSend 42Send "forty-two"
format: emailSend a@b.comSend not-an-email

Schema Validation in Practice

Validating with Postman

Use Postman’s built-in JSON Schema validation:

// In Tests tab
const schema = {
  type: "object",
  required: ["id", "name", "email"],
  properties: {
    id: { type: "number" },
    name: { type: "string" },
    email: { type: "string", format: "email" },
    role: { type: "string", enum: ["admin", "user", "viewer"] }
  },
  additionalProperties: false
};

pm.test("Response matches schema", function () {
  const response = pm.response.json();
  const valid = tv4.validate(response, schema);
  pm.expect(valid).to.be.true;
});

Validating with Python (jsonschema) 

import jsonschema
import requests

schema = {
    "type": "object",
    "required": ["id", "name", "email"],
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"}
    }
}

response = requests.get("https://api.example.com/users/1")
data = response.json()

try:
    jsonschema.validate(instance=data, schema=schema)
    print("Schema validation passed")
except jsonschema.ValidationError as e:
    print(f"Schema validation failed: {e.message}")

Automated Schema Testing with Schemathesis

Schemathesis generates test cases automatically from your OpenAPI spec:

pip install schemathesis

# Run against a live API
schemathesis run https://api.example.com/openapi.json

# With specific checks
schemathesis run https://api.example.com/openapi.json \
  --checks all \
  --stateful=links

It automatically tests boundary values, invalid types, missing fields, and more — all derived from the spec.

Testing Strategy Based on Specs

Spec vs. Implementation Testing

  1. Does the implementation match the spec? — Validate that actual responses conform to documented schemas
  2. Is the spec complete? — Check for undocumented endpoints, fields, or error codes
  3. Are constraints enforced? — Verify that minLength, maxLength, enum, format validations actually work
  4. Are edge cases handled? — Test nullable fields, optional fields, additional properties

Common Schema Bugs

BugHow to Find
Missing required fields in responseValidate against schema
Wrong data types returnedSchema validation catches string vs integer
Undocumented fields in responseUse additionalProperties: false
Enum values not enforcedSend invalid enum values in requests
Format not validatedSend malformed email, date, URI

Hands-On Exercise

  1. Read a spec: Explore the Petstore API spec in Swagger UI. Identify all endpoints, schemas, and required fields.
  2. Write a JSON Schema for a product object with: id (integer), name (string, 1-200 chars), price (number, min 0), category (enum), inStock (boolean).
  3. Validate responses: Use Postman to send requests to JSONPlaceholder and write schema validation tests for the /posts and /users endpoints.
  4. Find spec violations: Intentionally send invalid data and verify the API returns proper validation errors matching the spec.

Key Takeaways

  • OpenAPI specifications define the complete contract of an API — endpoints, parameters, request/response schemas, and authentication
  • JSON Schema provides validation rules (types, ranges, patterns, required fields) that map directly to test cases
  • Every schema constraint generates both positive and negative test scenarios
  • Automated tools like Schemathesis can generate comprehensive tests directly from OpenAPI specs
  • Schema validation catches data type mismatches, missing fields, and contract violations automatically