When we started Fern, we had to answer one question early: what format should API definitions live in? We landed on OpenAPI — and layered our own opinions on top where it falls short.
The case for OpenAPI
OpenAPI (formerly Swagger) is the de facto standard for describing HTTP APIs. Most teams already write some kind of spec, whether hand-authored or generated from code. Building on top of OpenAPI means:
- Zero adoption tax. Teams can point Fern at an existing spec and ship an SDK the same day.
- A huge ecosystem. Linters, validators, mock servers, documentation generators — they all speak OpenAPI.
- Future-proof. The spec keeps evolving, and there's a real community behind it.
Where we go further
OpenAPI isn't perfect. It's verbose, ambiguous in places, and wasn't designed with code generation as a first-class concern. So we added a thin layer on top that resolves those gaps — without forcing anyone to leave the standard.
| Feature | OpenAPI | Fern |
|---|---|---|
| Discriminated unions | partial | full |
| Streaming responses | — | yes |
| SDK-friendly errors | — | yes |
That's the short version. We'll go deeper on each of these in future posts.