Your OpenAPI spec is shipping a dead base URL

An OpenAPI spec is not just documentation, it is the contract a developer pastes into Postman, an SDK generator, or a try-it console. The first thing every one of those tools reads is the servers block: the base URL your endpoints hang off. Get it wrong and every example in your beautifully written spec resolves to nothing. It is the most-used field and the one most likely to be an afterthought.

Trap one: the placeholder that shipped

Specs are usually born with a servers entry of http://localhost:3000 or, worse, a templated https://{apiId}.example.com with a comment to replace it later. Later never comes. The spec gets published with the placeholder intact, and now your public API documentation tells the world to call localhost or a literal REPLACE_ME. It passes every test you have, because your tests hit the real URL directly and never read the spec’s servers block at all. The only person who hits it is the first external developer trying to use you.

Trap two: the AWS HTTP API stage path

This one is sneakier and specific to AWS API Gateway’s HTTP APIs (the v2 ones). People assume the base URL includes a stage prefix like /prod, the way the older REST APIs did, and they write https://host/prod into the servers block. But an HTTP API deployed to the $default stage has no path prefix. The real base is just https://host, and https://host/prod/jobs returns a 404 that looks like your endpoint is missing when in fact the stage segment should not be there at all. Hours disappear into debugging a route that was never wrong.

The fix: treat the base URL as deployed config

The servers block should not be hand-typed and hoped over. Generate it from the actually-deployed URL, the value your infrastructure already knows after a deploy, and inject it into the spec at build time. Then add the test almost nobody writes: hit the URL as documented, servers block plus a sample path, and assert it returns something real. That single check catches both traps, the localhost placeholder and the phantom stage prefix, before a developer ever sees them.

The broader point

A spec that does not point at a working server is worse than no spec, because it wastes the time of exactly the developer you most wanted to win over. The servers block deserves the same rigor as the endpoints themselves. It is the door; the rooms do not matter if the door opens onto a wall.

The plug

SnowScrape ships a real, public API, which is precisely why these traps came up: a documented base URL is part of the product, and it is tested as one. If you want public web data behind a clean API instead of a one-off script, it is at scrape.snowforge.dev.