Validating responses against the spec

// Checking real requests and responses against the operation the spec describes for them.

import { findOperation, resolveRef } from "./openapi.mjs";
import { validate } from "./validate.mjs";

/**
 * Does this response keep the contract? Returns a list of problems: a status the spec doesn't mention, a content
 * type it doesn't mention, a missing body, or a body that doesn't match the schema. An empty list means it does.
 */
export function checkResponse(spec, method, path, { status, contentType, body }) {
  const found = findOperation(spec, method, path);
  if (!found) return [`${method} ${path}: no such operation in the spec`];

  const where = `${method} ${found.template} ${status}`;
  const responses = found.operation.responses ?? {};
  const documented = responses[String(status)] ?? responses.default;
  if (!documented) return [`${where}: status ${status} isn't documented (documented: ${Object.keys(responses).join(", ")})`];
  if (!documented.content) return []; // the spec promises nothing about the body

  const type = contentType.split(";")[0].trim().toLowerCase();
  const media = documented.content[type];
  if (!media) {
    return [`${where}: content type ${type || "(none)"} isn't documented (documented: ${Object.keys(documented.content).join(", ")})`];
  }
  if (body === undefined) return [`${where}: the response has no body, but the spec describes one`];
  if (!media.schema) return [];

  return validate(media.schema, body, spec).map((problem) => `${where}: ${problem}`);
}

/**
 * Does this request keep the contract? Checks path parameters against their declared types and a JSON body against
 * the request body schema, so a client can find its own mistakes before blaming the server.
 */
export function checkRequest(spec, method, path, body) {
  const found = findOperation(spec, method, path);
  if (!found) return [`${method} ${path}: no such operation in the spec`];

  const where = `${method} ${found.template} request`;
  const problems = [];

  for (const parameter of found.operation.parameters ?? []) {
    const declared = parameter.$ref ? resolveRef(spec, parameter.$ref) : parameter;
    if (declared.in !== "path") continue;
    const raw = found.params[declared.name];
    const value = declared.schema?.type === "integer" && /^-?\d+$/.test(raw) ? Number(raw) : raw;
    problems.push(...validate(declared.schema ?? {}, value, spec, `path parameter ${declared.name}`).map((p) => `${where}: ${p}`));
  }

  const schema = found.operation.requestBody?.content?.["application/json"]?.schema;
  if (body !== undefined && schema) problems.push(...validate(schema, body, spec, "$body").map((p) => `${where}: ${p}`));

  return problems;
}

// Calls a handful of endpoints and checks every response against the spec.
// Run: node demos/check-api.mjs

import { send } from "../src/api.mjs";
import { checkResponse } from "../src/contract.mjs";
import { loadSpec } from "../src/openapi.mjs";

const spec = await loadSpec();
const requests = ["/api/Products/1", "/api/Products", "/api/Products/categories", "/api/Posts/1/comments", "/api/Todos/1", "/api/Products/9999"];

for (const path of requests) {
  const response = await send("GET", path);
  const problems = checkResponse(spec, "GET", path, response);
  console.log(`${problems.length ? "FAIL" : "ok  "}  GET ${path.padEnd(26)} ${response.status}`);
  for (const problem of problems) console.log(`      ${problem}`);
}

$ node demos/check-api.mjs
ok    GET /api/Products/1            200
ok    GET /api/Products              200
ok    GET /api/Products/categories   200
ok    GET /api/Posts/1/comments      200
ok    GET /api/Todos/1               200
ok    GET /api/Products/9999         404

// Lesson 4: real responses checked against the spec.

import assert from "node:assert/strict";
import { before, test } from "node:test";
import { send } from "../src/api.mjs";
import { checkResponse } from "../src/contract.mjs";
import { loadSpec } from "../src/openapi.mjs";

let spec;
before(async () => {
  spec = await loadSpec();
});

// Sends the request and returns the contract problems with its response.
async function problems(method, path, options) {
  const response = await send(method, path, options);
  return { response, problems: checkResponse(spec, method, path, response) };
}

for (const path of ["/api/Products/1", "/api/Products", "/api/Products/categories", "/api/Products/category/books",
  "/api/Posts/1", "/api/Posts/1/comments", "/api/Posts/user/101", "/api/Todos/1", "/api/Todos"]) {
  test(`GET ${path} keeps the contract`, async () => {
    const { response, problems: found } = await problems("GET", path);
    assert.equal(response.status, 200);
    assert.deepEqual(found, []);
  });
}

test("a 404 keeps the contract too: the documented Error shape", async () => {
  const { response, problems: found } = await problems("GET", "/api/Products/9999");
  assert.equal(response.status, 404);
  assert.deepEqual(found, []);
});

test("create, update and delete keep the contract", async () => {
  const created = await problems("POST", "/api/Todos", { body: { userId: 1, title: "contract test", priority: "low" } });
  assert.equal(created.response.status, 201);
  assert.deepEqual(created.problems, []);

  const id = created.response.body.data.id;
  try {
    const updated = await problems("PUT", `/api/Todos/${id}`, { body: { userId: 1, title: "contract test, updated", priority: "low" } });
    assert.deepEqual(updated.problems, []);
  } finally {
    const deleted = await problems("DELETE", `/api/Todos/${id}`);
    assert.deepEqual(deleted.problems, []);
  }
});

test("a broken response is caught: the same check on a doctored body", async () => {
  const response = await send("GET", "/api/Products/1");
  const doctored = { ...response.body, sale: true };
  delete doctored.price;
  assert.deepEqual(checkResponse(spec, "GET", "/api/Products/1", { ...response, body: doctored }), [
    'GET /api/Products/{id} 200: $: missing required property "price"',
    'GET /api/Products/{id} 200: $: unexpected property "sale"',
  ]);
});