# OpenAPI Specification

30 Hacker News commenters recommended OpenAPI Specification and 22 criticized it, November 2025 to November 2026. It was recommended in 10 of 13 months.

**Verdict:** Widely used standard for describing REST APIs, letting tools generate code, docs and validation. Caveat: specs often go stale and tooling lags on newer versions.

## Why people recommend it

- Turns specs into LLM tool calls (4 comments): "A good OpenAPI spec was working perfectly fine for me all the way back when OpenAI introduced GPTs." ([source](https://news.ycombinator.com/item?id=47258795)) "just adding some semi-standard attributes to OpenAPI specs to make them more LLM consumable" ([source](https://news.ycombinator.com/item?id=49910469)) "OpenAPI 3.0 has auth. You can turn OpenAPI specs into tool calls just as well" ([source](https://news.ycombinator.com/item?id=49182916))
- Generates typed clients and SDKs (4 comments): "developing against a spec, like OpenAPI, and using/building an auto-generated SDK is still very useful for coding agents" ([source](https://news.ycombinator.com/item?id=47571360)) "But you know what also gives you auto-generated code that works perfectly without a hitch, with full schema validation?" ([source](https://news.ycombinator.com/item?id=46741463)) "I really like OpenAPI in conjunction with openapi-fetch to create a typed interface" ([source](https://news.ycombinator.com/item?id=47936109))
- Self-documenting API description (3 comments): "having a document describing how your API works, including types, that is important" ([source](https://news.ycombinator.com/item?id=46042714)) "Pair it with OpenAPI and the whole thing is self-documenting." ([source](https://news.ycombinator.com/item?id=49180013)) "It addresses all the key description and security details." ([source](https://news.ycombinator.com/item?id=49783516))
- Broad tool and language support (2 comments): "OpenAPI is great, there are a lot of tools to go from OpenAPI to UI, but you don't have a lot of control over the presentation." ([source](https://news.ycombinator.com/item?id=46748320)) "OpenAPI supports a lot of languages, not just 2." ([source](https://news.ycombinator.com/item?id=45974102))

## What people warn about

- Specs often outdated or incomplete (3 comments): "the issue we face is that REST API specs for many products are either missing, incomplete or simply outdated" ([source](https://news.ycombinator.com/item?id=46267919)) "Specs drift from reality, documentation lies, and you're trusting convention" ([source](https://news.ycombinator.com/item?id=46269859)) "Most existing OpenAPI specs out there don't clear that bar" ([source](https://news.ycombinator.com/item?id=46214662))
- Tooling lags on newer versions (3 comments): "Many users are stuck at 3.0 or even Swagger 2.0 because the libraries they use refuse to support recent versions" ([source](https://news.ycombinator.com/item?id=46083886)) "open-api 3.1 is still not viable, and isn't looking like it will be anytime soon." ([source](https://news.ycombinator.com/item?id=46084353)) "OpenAPI is really outdated and the tooling is always a mess." ([source](https://news.ycombinator.com/item?id=47086135))
- Seen as a mediocre solution (2 comments): "using something like OpenAPI to share the schema is a subpar solution" ([source](https://news.ycombinator.com/item?id=47352877)) "OpenAPI (which I've used and it's a mediocre solution)" ([source](https://news.ycombinator.com/item?id=45922934))

## Alternatives hackers recommend

- [TypeSpec](https://hackerapproved.com/p/typespec.md): 11 recommend
- [Skir](https://hackerapproved.com/p/skir.md): 7 recommend
- [Swagger](https://hackerapproved.com/p/swagger.md): 6 recommend

## Cite as

Hacker Approved, "OpenAPI Specification", https://hackerapproved.com/p/openapi/ (counts from 1,795,640 Hacker News comments, November 2025 to November 2026).