Agent WranglersContracts and docs
Make an OpenAPI file the single source of truth. Test the API against it, generate docs and clients from it, and publish it for people and agents.
- Required 3
- Recommended 2
Required
Write the contract first
RequiredDescribe every endpoint, parameter, body, response and error in one OpenAPI document, kept in version control next to the code.
Test the API against its contract
RequiredRun tests that send requests and validate every response against the contract.
Generate docs and clients from the contract
RequiredBuild the reference docs from the OpenAPI file, not by hand. Generating SDKs from it too is optional.
Recommended
Give every endpoint an example
RecommendedAdd a realistic request and response example to every operation in the contract.
Make the API easy for agents to find
RecommendedLink the contract from a well-known place, so AI agents and tools can find and use the API without a human.
For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/contracts-and-docs.