Topic
A 429 with no Retry-After just makes clients guess, hammer harder, or give up. A usable rate-limit contract states the quota window, the remaining count, and exactly when to retry. Here is how to model 429, Retry-After, and the RateLimit headers in OpenAPI and verify the backoff with a mock.
Read articleTwo clients PUT the same resource and the last write silently wins. The HTTP fix is conditional requests with ETag, If-Match, and a 412 that tells the client to re-fetch and retry. Here is the exact state table and the OpenAPI that makes codegen and AI agents handle conflicts correctly.
Read articleMost OpenAPI upload specs are subtly wrong: the file is typed as a string, the multipart boundary is undocumented, or an array of files generates the wrong client. Here is how to model each of the three real upload shapes so codegen, mocks, and scanners all agree.
Read articleThe same example payload is usually hand-copied into docs, a mock server, a Postman collection, and test fixtures, and then they drift. OpenAPI examples can drive all four from one document, but only if they are realistic, schema-valid, and cover success, empty, and error states.
Read articleVersioning is less about where the number goes than about knowing what actually breaks a client and communicating the sunset. Here is the honest tradeoff between path and header versioning, a breaking-change checklist, and how to enforce it with OpenAPI diffs in CI.
Read articleMost OpenAPI auth docs are subtly wrong: a scheme is defined but never applied, a token is modeled as a plain header, or OAuth scopes do not match the server. Here is how to document each mechanism correctly, combine them with AND/OR semantics, and mark public endpoints.
Read articleInline every schema and your request and response models drift apart. Extract everything and the document becomes a maze of one-off references. The middle path is a small set of rules for what becomes a component, what stays inline, and how to name and compose it.
Read articleAsking an LLM to read your whole codebase and emit OpenAPI produces fluent, non-reproducible fiction. Pure AST scanning is reproducible but goes blind on dynamic serializers. The reliable design is static analysis first, with AI filling only proven gaps a human can review.
Read articleFastAPI puts contracts in annotations; Django REST puts them in serializers and viewsets. A static scanner can recover both without a running server, but the dynamic parts of DRF, external models, source mappings, and runtime choices, must be reported as gaps rather than turned into invented enums.
Read articleExpress has no built-in schema layer and NestJS Swagger decorators drift the moment a DTO changes. A deterministic scanner can prove routes from the real framework instance and recover schemas from TypeScript types, leaving explicit, reviewable gaps instead of guesses.
Read articleFree-form tool arguments are where agent workflows break: the model invents fields, sends numbers as strings, and omits required values. Structured outputs backed by strict JSON Schema make tool calls deterministic, and most of that schema already exists in your OpenAPI components.
Read articleAgents guess field names when they never see the contract. Serve the spec over MCP, generate one verified vertical slice at a time, run scenarios against localhost, and rescan to catch drift.
Read article