Handing an OpenAPI Spec to a Coding Agent
The spec is the contract. When the docs and the spec disagree, the agent has to pick one, and you need to know which.
Why a spec at all
A coding agent will happily guess an API. It has seen a hundred headless CMSs and will assume yours works like the average of them. A project-specific OpenAPI spec replaces the guess with a contract.
The first prompt
The first step was not code. It was a table: every endpoint the app needs, with path, parameters and response fields, taken only from the spec. Anything missing was written down as missing.
Where sources disagreed
- Some doc examples list posts at
/tables/posts/contents; the spec says/tables/posts - The spec describes
sortasname:asc; a doc example uses a JSON array
The app follows the spec, and the build log records each disagreement so it can be checked against real responses.
Takeaway
Ask the agent to cite where each field came from. Uncited fields are guesses.