Products · Product
OpenAPI
Raised as a usability problem by 22 people on Hacker News over 9 years (2017–2025), in 17 threads.
No issue was raised by at least 3 people in 3 threads this year.
No issue was raised by at least 3 people in 3 threads in the last 5 years.
Every issue, all time, most people first
Ambiguous oneOf, anyOf and allOf behaviour makes tooling hard to implementUnreviewed
20172026- Nested anyOf, allOf and oneOf produce confusing, hard-to-follow specifications2024-03-27
- Generated SDKs are unreadable and unusable, especially with allOf/anyOf/oneOf composition2022-08-31
- OneOf/anyOf/allOf behaviour is ambiguous, hard to implement tooling for2019-04-15
Unreviewed issues were grouped by machine: Claude Haiku labelled each comment as a usability complaint, named what it's about and summed up the problem in a line, and a small model grouped similar problems. Nobody has checked them by hand. Expect mistakes.
The newest 22 complaints
- Endpoint and parameter descriptions are underdocumented, so the API is unusable without external docs2025-12-10
- Single-method descriptions span screens; huge YAML files useless without splitting tools2025-06-19
- New-version docs advise approaches that tooling often doesn't support, causing breakage2025-01-23
- OpenAPI UI editors are unusable for complex JSON specifications2024-09-20
- Can't add descriptions next to $ref, so reused structures can't be documented2024-03-28
- Hard to read JSON, and YAML is quirky when split into parts2024-03-27
- Nested anyOf, allOf and oneOf produce confusing, hard-to-follow specifications2024-03-27
- Clicking around the OpenAPI client is slower than making a curl call2024-03-02
- Tools turning OpenAPI specs into code or docs are broken, with known bugs left unfixed for years2023-06-23
- Official generator is very hard to modify or extend2023-06-01
- YAML specs become hard to maintain once they cover more than a few endpoints2023-06-01
- Users find the OpenAPI specification painful to work with2023-05-31
- Wasted weeks getting broken code generation tools to work2023-01-31
- Too difficult to use for generating Go structs and helpers2022-10-16
- Generated SDKs are unreadable and unusable, especially with allOf/anyOf/oneOf composition2022-08-31
- Tooling support for OpenAPI features is inconsistent, and spec deviations make specs complicated2022-01-25
- Large OpenAPI YAML files lack editor autocomplete and type checking, making them hard to manage2021-09-05
- The OpenAPI DSL is too verbose and hard to write by hand2021-08-28
- Generated client and server code is unusable, so users write their own instead2020-02-21
- Bearer token JWT auth is confusing to configure, and client structure is unintuitive2020-02-21
- OneOf/anyOf/allOf behaviour is ambiguous, hard to implement tooling for2019-04-15
- Search freezes the whole page for about 30 seconds after typing on mobile2017-12-26