Swagger and OpenAPI for Testers: Read Specs and Generate Tests

On most projects the first thing you get for a new API is a link to its Swagger page. Testers who can read an OpenAPI specification properly start testing on day one, spot gaps in the contract before code is written, and generate collections, mocks and even test cases from it in minutes. This lesson teaches you to read and use OpenAPI as a tester, with a real specification for part of the SQA Tools practice API.

Swagger vs OpenAPI: Names Explained

So “send me the Swagger” usually means “send me the OpenAPI file or the Swagger UI link”. The official demo is the Petstore at petstore3.swagger.io; open it in a new tab to explore while you read.

Anatomy of an OpenAPI File

Here is an OpenAPI 3.0 description of three practice API endpoints. Read it top to bottom:

openapi: 3.0.3
info:
  title: SQA Tools Practice API
  version: 1.0.0
servers:
  - url: https://sqatools.in/wp-json/sqa-api/v1
paths:
  /users/{id}:
    get:
      summary: Get one user
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, minimum: 1 }
      responses:
        '200':
          description: The user
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/User' }
        '400': { $ref: '#/components/responses/Error' }
        '404': { $ref: '#/components/responses/Error' }
  /objects:
    post:
      summary: Create a temporary object
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NewObject' }
      responses:
        '201':
          description: Created
          headers:
            Location: { schema: { type: string, format: uri } }
            ETag:     { schema: { type: string } }
        '413': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
  /auth/me:
    get:
      security: [ { bearerAuth: [] } ]
      responses:
        '200': { description: Current user }
        '401': { $ref: '#/components/responses/Error' }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
  schemas:
    User:
      type: object
      required: [id, name, username, email, role, city, age, active, created_at]
      additionalProperties: false
      properties:
        id:         { type: integer, minimum: 1 }
        name:       { type: string }
        username:   { type: string }
        email:      { type: string, format: email }
        role:       { type: string, enum: [admin, editor, viewer] }
        city:       { type: string }
        age:        { type: integer, minimum: 18 }
        active:     { type: boolean }
        created_at: { type: string, format: date-time }
    NewObject:
      type: object
      required: [name]
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 100 }
        data: { type: object }
        ttl:  { type: integer, minimum: 10, maximum: 1800, default: 600 }
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                required: [status, code, message]

Reading it as a tester

Using Swagger UI to Test

1. Open the Swagger UI link. Operations are grouped by tags.
2. Click Authorize and paste your token or key once; it’s applied to secured calls.
3. Expand an operation → Try it out → fill parameters/body → Execute.
4. Swagger UI shows the cURL command, request URL, response code, body and headers.
5. Compare the actual response with the documented one below it. Every mismatch is a bug in the API or in the docs.

Finding Bugs in the Spec Itself (Shift-Left)

Reviewing the spec before development is one of the highest-value things a tester can do. Questions to ask:

• Missing limits: name: { type: string } with no maxLength. What happens with 1 MB?
• Missing error responses: only 200 documented. What about 400, 401, 404, 422, 429?
• Ambiguous types: money as number (float) instead of integer paise or a decimal string.
• Inconsistent naming: userId in one place, user_id in another.
• Missing pagination on list endpoints that will grow.
• Security gaps: sensitive endpoints without security.
• Enum changes: are new values allowed later without breaking mobile apps?

Spec vs Reality: Contract Testing

The spec is only useful if the API matches it. Compare them:

• Schema validation of every response against the spec’s schemas (Ajv in Playwright, jsonSchema in Postman).
• Undocumented endpoints: list what’s deployed and compare. The practice API exposes a discovery endpoint you can diff against docs:

curl -i \
  "https://sqatools.in/wp-json/sqa-api/v1/endpoints"

• Undocumented status codes: the API returns 409 but the spec never mentions it.
• Breaking changes between versions: tools like openapi-diff or oasdiff compare two spec files and flag removed endpoints, new required fields or changed types. Run them in CI on every pull request that touches the spec.

Generating Things from the Spec

# Mock the API locally from the spec
npx @stoplight/prism-cli mock openapi.yaml          # serves on http://127.0.0.1:4010

# Fuzz the real (test) API from the spec
pip install schemathesis
schemathesis run openapi.yaml --url https://qa.example.com/api --checks all

# Detect breaking changes between two versions of the spec
oasdiff breaking old-openapi.yaml new-openapi.yaml

Using the Spec in Playwright Tests

import { test, expect } from '@playwright/test';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import fs from 'node:fs';
import YAML from 'yaml';

const spec = YAML.parse(fs.readFileSync('openapi.yaml', 'utf8'));
const ajv = new Ajv({ allErrors: true, strict: false });
addFormats(ajv);
const validateUser = ajv.compile(spec.components.schemas.User);
const BASE = spec.servers[0].url;

test('GET /users/{id} matches the OpenAPI User schema', async ({ request }) => {
  for (const id of [1, 2, 3]) {
    const res = await request.get(`${BASE}/users/${id}`);
    expect(res.status()).toBe(200);
    const ok = validateUser((await res.json()).data);
    expect(ok, JSON.stringify(validateUser.errors)).toBe(true);
  }
});

test('every documented error code for /users/{id} is reachable', async ({ request }) => {
  const documented = Object.keys(spec.paths['/users/{id}'].get.responses);   // ['200','400','404']
  const seen = new Set([
    (await request.get(`${BASE}/users/1`)).status(),
    (await request.get(`${BASE}/users/abc`)).status(),
    (await request.get(`${BASE}/users/999`)).status(),
  ].map(String));
  expect([...seen].sort()).toEqual(documented.sort());
});

The tests now fail automatically when the API drifts from its contract or the contract changes without the tests.

Writing Spec-Based Test Cases: A Quick Recipe

1. For each operation, list every documented response code: one test each.
2. For each parameter and body field: required/optional, type, format, min/max, enum → negative and boundary tests.
3. For each security requirement: no token, invalid token, wrong role.
4. For each response schema: schema validation on positive tests.
5. For each response header: assertion.
6. Then add what the spec can’t express: business rules, state transitions, cross-field rules, performance.

Common Mistakes

• Trusting the spec blindly. It’s often out of date; the tests should prove it.
• Only using Swagger UI for manual clicks and never importing the spec into tools.
• Ignoring required and nullable differences (missing vs null).
• Not versioning the spec in Git alongside the code.

Interview Questions: Swagger and OpenAPI