API Docs and Specs
Connect OpenAPI 3.2, tool schemas, MCP Resources, and contract tests.
Key takeaways
- API docs are contracts: they fix request/response shapes, auth scopes, side effects, reliability rules, and validation, which agents use for codegen, tests, debugging, and MCP Tool design.
- Treat the schema (OpenAPI/JSON Schema) as the source of truth over prose, and keep
operationIdstable because SDK and tool mappings depend on it. - OpenAPI 3.2.0 (released September 19, 2025) suits new projects, but a newer spec does not guarantee validator, codegen, gateway, or renderer support, so verify the full toolchain first.
- Map API doc items to MCP Tool fields (schemas to
inputSchema/outputSchema, auth to authorization, side effects to annotations and approval policy). - Detect breaking changes (added required field, removed/retyped response field, removed enum value) and gate them with migration notes and
openapi:diff.
API docs are among the most frequently used references for coding agents. Agents use them for code generation, tests, debugging, MCP Tool design, and SDK generation.
An agent-first API document needs a source of truth, examples, side-effect boundaries, and validation.
API Docs Are Contracts
| Contract | Example |
|---|---|
| Request shape | path, query, body, headers |
| Response shape | success and error schemas |
| Auth | OAuth scope, API key, role |
| Side effect | read-only, write, destructive, external |
| Reliability | idempotency, retry, rate limit |
| Validation | lint, diff, contract test |
OpenAPI Version Choice
The latest published OpenAPI version is 3.2.0, released on September 19, 2025.
| Version | Recommended use |
|---|---|
| 3.2.0 | new projects, streaming APIs, query, tag taxonomy, OAuth metadata |
| 3.1.x | when tooling has not fully adopted 3.2 but JSON Schema 2020-12 matters |
| 3.0.x | legacy tooling constraints |
Separate Spec Version From Tool Support
A newer spec version does not guarantee every validator, code generator, gateway, or docs renderer supports it. Verify the full toolchain before switching.
Principles
- Schema is source of truth - OpenAPI/JSON Schema beats prose.
- Stable
operationId- SDK and tool mappings depend on it. - Examples first - include request, response, and error examples.
- Error contracts - include status, code, message, and recovery action.
- Side effects - document read/write/destructive/open-world behavior.
- Validation - document lint, diff, contract tests, and smoke tests.
Agent Contract Pack
api-contract/
├── openapi.yaml
├── errors.md
├── auth.md
├── rate-limits.md
├── idempotency.md
├── examples/
└── validation.mdOpenAPI 3.2 Items to Watch
| Item | Documentation impact |
|---|---|
| streaming media types | clearer SSE, JSON Lines, JSON Sequences, multipart/mixed |
query method | safe query behavior with payload |
querystring | schema for the whole query string |
| expanded tags | better navigation and codegen grouping |
| OAuth metadata URL | auth server discovery in the API contract |
MCP Tool Mapping
| API doc item | MCP Tool doc item |
|---|---|
| path/query/body schema | inputSchema |
| response schema | outputSchema or structured content |
| auth/scope | MCP authorization |
| read/write/destructive | annotations and approval policy |
| rate limit | retry/backoff policy |
| error code | Tool error and recovery |
MCP Tool annotations are hints, not guarantees. Do not treat readOnlyHint or destructiveHint as
the security boundary.
Breaking Change Detection
| Change | Risk | Action |
|---|---|---|
| required request field added | breaking | migration note |
| response field removed or type changed | breaking | consumer impact |
| enum value removed | breaking | client fallback review |
| optional field added | usually non-breaking | docs/examples update |
| new error code | conditional | client handling review |
pnpm openapi:lint
pnpm openapi:diff --from main --to HEAD
pnpm test:contractPrompt
Update the API docs using only the route handlers and OpenAPI files below.
Include operationId, auth, scope, schemas, examples, errors, idempotency, rate limits,
MCP Tool mapping, breaking-change assessment, and validation commands.
Do not invent parameters or tool annotations.