The Powerduck Blog
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesThe field changed in code, in chat, and in the HTTP client while the docs waited for someone to care. A local OpenAPI file in version control gives the whole team one contract to diff, review, and trust.
Read articlePostman collections, mock servers, docs generators and MCP glue all drift the moment the spec stops being the source of truth. Powerduck keeps one local OpenAPI file at the center.
Read articleOffset pagination is easy until data changes under the client; cursors are stable but opaque and bad for jump-to-page. Here is how to choose, how to document each style in OpenAPI 3.2, and the response envelope that stops frontend teams guessing.
Read articleA 4,000-line YAML file is unmaintainable, but splitting a spec wrong creates a web of relative refs that no editor or bundler can resolve. Here is a folder layout that scales past 200 operations, the $ref conventions that keep it sane, and the CI checks that keep it honest.
Read articleAutomatic converters handle the mechanical 80 percent and quietly break the other 20: nullable fields, consumes/produces, body parameters, security definitions, and examples. Here is the migration checklist that actually gets a 2.0 spec to 3.2 without lying to consumers.
Read articleStoplight Studio's desktop editor is no longer maintained, and teams are re-evaluating what an OpenAPI editor should be: a visual form, a YAML IDE, or a workspace where the spec also drives mocks, tests, and MCP. Five options compared on real work.
Read articleCode-first won the 2010s because annotations were cheaper than maintaining a spec. AI agents and code generation flipped the economics: the contract is now the interface your newest consumer reads. Here is how to actually decide, team by team.
Read article