What it is
A published OpenAPI document at a predictable path lets a client discover your operations, parameters and auth without a human reading your docs first.
Developer documentation is a partial substitute — an agent can read it — but prose has to be interpreted, and interpretation is where integrations break.
Why an agent cares
Every integration that requires a human to read documentation is an integration that happens at human speed, if it happens.
A machine-readable spec is also the input to generated clients, MCP servers and evaluation harnesses — one artefact, several unlocks.
How to fix it
- Publish
openapi.jsonat a stable path and link it from your docs. - Generate it from your route definitions so it can't drift.
- Document auth and rate limits inside the spec, not only in prose.
How we test it
We probe the common spec paths and confirm the payload is really an OpenAPI or Swagger document, then look for linked developer documentation as a partial credit.