OpenAPI default Values: Convenient for Docs, Dangerous for Validation
Quick answer: A default in OpenAPI documents what a server or client may assume when a property is absent, but it is not a validation instruction and it does not
Read articleTopic
openapi
Codegen vs additionalProperties: When Free-Form Maps Break Typed Clients
Quick answer: An OpenAPI schema with additionalProperties describes a free-form map keyed by strings, and how a code generator turns that into typed code varies a lot between languages and
Read articleBundling Multi-File OpenAPI: $ref Resolution Compared
Quick answer: Splitting an OpenAPI document across files is the right move for large APIs, but every tool that consumes the spec — docs, mock servers, code generators, gateways — needs a
Read articleVersioned Docs for Multiple API Versions: Mintlify vs Spec Branches
Quick answer: Versioned documentation is only worth its complexity if you actually support multiple live API versions; for a single evolving API, a well-managed deprecation policy with one current spec
Read articleDesigning Cursor Pagination: Why Offset Hits a Wall
Quick answer: Offset pagination is simple and correct for static, small result sets, but it breaks down on live data: as rows are inserted or deleted between requests, pages skip
Read articleGenerated Enums Break When the API Adds a New Value
Quick answer: A generated enum is a closed set by default, so the moment the server adds a value the client did not know about, strict generated code can throw,
Read articleThe OpenAPI Guide: Spec, 3.2, Design, and How It Works
Quick answer: OpenAPI is a machine-readable contract that describes an HTTP API — its paths, operations, request and response shapes, authentication, and examples. Treat it as the single source of truth
Read articlePostman vs Bruno vs a local-first OpenAPI studio: choose by where the spec lives
Postman, Bruno, and a local-first OpenAPI studio optimize a different assumption about where the API contract lives: a cloud collection, plain files in git, or the spec itself. The right choice follows that assumption, not UI polish. Here are the honest tradeoffs and a short decision checklist.
Read articleYour saved API example keeps passing against the mock and fails against the live backend
The saved request in your API client and the recorded mock were hand-written once and never re-validated. The mock accepts the old payload and local replay stays green until the deployed backend rejects it. Derive examples from the spec, regenerate mocks on change, and validate before replay.
Read articleWe Committed the Generated Types to the Repo; CI Stayed Green While the Server Dropped the Field
The generated SDK lived in the repo as a checked-in snapshot. CI typechecked against it, the server quietly removed a field upstream, and production kept reading undefined while every build passed.
Read articleThe Agent Bumped a Major Version and CI Stayed Green
The agent bumped a dependency across a major version, CI stayed green, and the nightly job kept logging success while silently returning the first page of records. The mock passed; the installed package had changed.
Read articlePin baseUrl in the Gateway, Not in the Agent's Prompt
The OpenAPI spec lists prod as the first server. Your agent reads it and calls prod on every test run. The fix is not another line in the system prompt.
Read article