OneLinersCommand workbench
AI
Back to skills
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
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/api-docs-review/SKILL.md
Claude Code.claude/skills/api-docs-review/SKILL.md
VS Code.github/skills/api-docs-review/SKILL.md

Trust 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.

Source evidence

Agent Skills specificationofficialOpenAPI SpecificationofficialOpenAPI Specification 3.1.1 — versioned descriptionofficial