SKILL.md
API documentation reviewer
An evidence-first workflow to verify that integration documentation matches the published API contract and real failure behavior.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/api-docs-review/SKILL.mdClaude Code
.claude/skills/api-docs-review/SKILL.mdVS Code
.github/skills/api-docs-review/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: api-docs-review
description: Checks exact integration examples against versioned API shapes, successful traversal and failure behavior. Use when authentication, pagination or error docs may mislead a consumer; distinguish schema descriptions, fixture behavior and deployed evidence.
license: CC-BY-4.0
compatibility: Complete owned API exercise uses Node.js 22.13+ Request/Response without network or a real token. OpenAPI reference is explicitly 3.1.1; real contract validation and staging calls require the supported provider toolchain/scope.
metadata:
author: oneliners
version: "2.0.0"
---
# API documentation reviewer
## Begin with the consumer journey and contract version
Identify API version, base URL, supported client, required identity/permissions and one bounded task. Collect the published contract, a full request/response pair and an actual failure example from an authorized environment. Specify whether the API description, implementation or sample is wrong; do not silently change a contract to make a bad example valid. An OpenAPI security scheme describes a mechanism, not object-level access decisions.
## Original integration drift input
The fictional old quick start claims: "Call GET /v1/widgets?page=2&limit=0 without a header; read the data array; errors are empty arrays; next_cursor is always a string." The complete owned handler below is the supplied behavior authority. It uses synthetic constant fixture identities and a three-item frozen dataset, not a token issuer or live service.
The corresponding complete versioned description is included so the reader does not need an unavailable OpenAPI file:
```json
{
"openapi": "3.1.1",
"info": {
"title": "Owned widgets documentation fixture",
"version": "2.0.0"
},
"paths": {
"/v1/widgets": {
"get": {
"operationId": "listWidgets",
"security": [
{
"fixtureBearer": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 2,
"default": 2
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
},
"description": "Opaque next_cursor from a prior response; omit on first request."
}
],
"responses": {
"200": {
"description": "One page; next_cursor null ends traversal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Page"
}
}
}
},
"400": {
"description": "Invalid limit/cursor or unsupported/duplicate parameter",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or unrecognized fixture credential",
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Known fixture credential has no read permission",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"fixtureBearer": {
"type": "http",
"scheme": "bearer",
"description": "Transport shape only; the local handler uses explicitly synthetic fixture values, not a real token service."
}
},
"schemas": {
"Page": {
"type": "object",
"required": [
"items",
"next_cursor"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"label"
],
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
}
}
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
}
},
"Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
}
}
}
}
}
}
}
}
```
## Execute exact local examples, including failure paths
Save the entire next block as api-docs-fixture.mjs and run node api-docs-fixture.mjs with Node.js 22.13+. No package, server, data file or network request is used. example.invalid only names a Request object; it is never contacted.
```js
import assert from "node:assert/strict";
function handleDocsRequest(request) {
const url = new URL(request.url);
assert.equal(request.method, "GET"); assert.equal(url.pathname, "/v1/widgets");
const error = (status, code, message) => Response.json({ error: { code, message, request_id: "fixture-r1" } }, { status, headers: status === 401 ? { "WWW-Authenticate": 'Bearer realm="owned-fixture"' } : {} });
const authorization = request.headers.get("authorization");
if (authorization === "Bearer fixture-viewer-no-read") return error(403, "forbidden", "Read permission required");
if (authorization !== "Bearer fixture-reader-not-a-real-token") return error(401, "unauthorized", "Use the documented owned fixture identity");
for (const key of url.searchParams.keys()) if (!["limit", "cursor"].includes(key) || url.searchParams.getAll(key).length !== 1) return error(400, "invalid_parameter", "Unsupported or repeated parameter");
const rawLimit = url.searchParams.get("limit") ?? "2";
if (!/^[12]$/.test(rawLimit)) return error(400, "invalid_limit", "limit must be 1 or 2");
const cursor = url.searchParams.get("cursor");
const offsets = { "opaque-B": 1, "opaque-C": 2 };
if (cursor !== null && !Object.hasOwn(offsets, cursor)) return error(400, "invalid_cursor", "Pass next_cursor unchanged");
const offset = cursor === null ? 0 : offsets[cursor], limit = Number(rawLimit);
const items = [{ id: "w1", label: "Alpha" }, { id: "w2", label: "Beta" }, { id: "w3", label: "Gamma" }];
const nextOffset = offset + limit;
const next = nextOffset >= items.length ? null : nextOffset === 1 ? "opaque-B" : "opaque-C";
return Response.json({ items: items.slice(offset, nextOffset), next_cursor: next });
}
async function runApiDocsLab() {
const call = (query, authorization) => handleDocsRequest(new Request("https://example.invalid/v1/widgets" + query, { headers: authorization ? { Authorization: authorization } : {} }));
const credential = "Bearer fixture-reader-not-a-real-token";
const checks = [["missing credential", "?limit=2", null, 401, "unauthorized"], ["no read permission", "?limit=2", "Bearer fixture-viewer-no-read", 403, "forbidden"], ["old page parameter", "?page=2", credential, 400, "invalid_parameter"], ["zero limit", "?limit=0", credential, 400, "invalid_limit"], ["invented cursor", "?cursor=page2", credential, 400, "invalid_cursor"]];
const failures = [];
for (const [name, query, auth, expected, code] of checks) {
const response = call(query, auth), body = await response.json();
assert.equal(response.status, expected); assert.equal(body.error.code, code); assert.equal(body.error.request_id, "fixture-r1");
if (expected === 401) assert.ok(response.headers.get("www-authenticate"));
failures.push({ name, status: response.status, error: body.error.code });
}
const pages = [], ids = [], seen = new Set(); let cursor = null;
for (let page = 0; page < 3; page++) {
const query = new URLSearchParams({ limit: "2" }); if (cursor !== null) query.set("cursor", cursor);
const response = call("?" + query.toString(), credential); assert.equal(response.status, 200);
const body = await response.json(); assert.ok(Array.isArray(body.items));
pages.push(body); ids.push(...body.items.map((item) => item.id));
cursor = body.next_cursor; if (cursor === null) break;
assert.equal(typeof cursor, "string"); assert.ok(!seen.has(cursor), "repeating cursor"); seen.add(cursor);
}
assert.equal(cursor, null, "bounded traversal must reach the terminal page");
assert.deepEqual(ids, ["w1", "w2", "w3"]); assert.equal(new Set(ids).size, ids.length);
return { failures, pages, ids, scope: "Native Request/Response objects and actual local handler executions only. No HTTP request or real authentication." };
}
console.log(JSON.stringify(await runApiDocsLab(), null, 2));
```
## Findings and reproducible corrected traversal
The old integration instructions are not merely missing prose: no credential yields 401/unauthorized; the known no-read fixture identity yields 403/forbidden; page=2 yields 400/invalid_parameter; limit=0 yields 400/invalid_limit; an invented cursor yields 400/invalid_cursor. Each actual local error body is {error:{code,message,request_id}}, not a successful page with an empty data array. The 401 also carries WWW-Authenticate. These synthetic strings are not usable credentials.
Correct happy path: send the fixture reader header, GET /v1/widgets?limit=2 with no cursor. The actual first body has items w1/w2 and next_cursor opaque-C. Pass that returned value unchanged on the next GET; the second body has w3 and next_cursor null. Both statuses are 200, all three IDs are unique, and the bounded traversal terminates. Do not turn a token into a guessed page number or treat the nullable cursor as a required string.
Document the supported limit/default, opaque cursor lifecycle, authentication transport versus permission failure, content type, successful envelope and real error codes together. The complete OpenAPI 3.1.1 document describes those shapes; the executed handler verifies this fixture's examples, not conformance of a deployed service or a full OpenAPI toolchain. Examples need schema checks in the actual consumer tooling too.
Do not automatically retry malformed requests or permission failures. Rate limits, cursor expiry, mutable-dataset consistency and production base URL/credential issuance are not established here; request their actual contracts rather than inventing headers or guarantees. The code constructs native Request/Response objects but never invokes fetch or opens a port. For a real API review, compare the published version/spec with authorized staging transcripts and preserve old version URLs, client compatibility and documented deprecations.
## Publish docs with evidence and known gaps
Use the explicit [OpenAPI 3.1.1 reference](https://spec.openapis.org/oas/v3.1.1.html) for this document, not an unversioned assumption about the newest feature set. Record request method/path/query/header encoding, content types, response status/schema, failure semantics and the bounds under which a pagination example was tested. Link actual auth setup and compatibility policy when known; never insert private tokens into documentation. Stop a claimed quick start when required credentials, versions, input or production semantics are missing. Changing docs does not authorize a production call, destructive test or API behavior change.
Real example
Input
Review the old widgets quick start, full OpenAPI 3.1.1 document and exact local handler in SKILL.md. Verify missing/no-read identities, old pagination/limit/cursor failures and a bounded complete traversal. Distinguish fixture Request/Response execution from real HTTP or provider authentication.
Expected result
The old integration instructions are not merely missing prose: no credential yields 401/unauthorized; the known no-read fixture identity yields 403/forbidden; page=2 yields 400/invalid_parameter; limit=0 yields 400/invalid_limit; an invented cursor yields 400/invalid_cursor. Each actual local error body is {error:{code,message,request_id}}, not a successful page with an empty data array. The 401 also carries WWW-Authenticate. These synthetic strings are not usable credentials.
Correct happy path: send the fixture reader header, GET /v1/widgets?limit=2 with no cursor. The actual first body has items w1/w2 and next_cursor opaque-C. Pass that returned value unchanged on the next GET; the second body has w3 and next_cursor null. Both statuses are 200, all three IDs are unique, and the bounded traversal terminates. Do not turn a token into a guessed page number or treat the nullable cursor as a required string.
Document the supported limit/default, opaque cursor lifecycle, authentication transport versus permission failure, content type, successful envelope and real error codes together. The complete OpenAPI 3.1.1 document describes those shapes; the executed handler verifies this fixture's examples, not conformance of a deployed service or a full OpenAPI toolchain. Examples need schema checks in the actual consumer tooling too.
Do not automatically retry malformed requests or permission failures. Rate limits, cursor expiry, mutable-dataset consistency and production base URL/credential issuance are not established here; request their actual contracts rather than inventing headers or guarantees. The code constructs native Request/Response objects but never invokes fetch or opens a port. For a real API review, compare the published version/spec with authorized staging transcripts and preserve old version URLs, client compatibility and documented deprecations.