Tapir
Type-safe HTTP API definition library for Scala that generates both server implementations and OpenAPI documentation from a single endpoint description. Tapir endpoints are typed values: endpoint.in('path' / 'resource').in(jsonBody[RequestType]).out(jsonBody[ResponseType]).errorOut(statusCode). The same endpoint definition can generate http4s, Akka HTTP, or ZIO HTTP server routes, a Scala client, and OpenAPI 3 docs. 'Write once, deploy anywhere, document for free.'
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Type-safe input/output prevents implicit data leakage. Explicit error outputs prevent information disclosure in 500s. SecurityIn models auth requirements explicitly. No external network calls.
⚡ Reliability
Best When
You're building Scala APIs that need accurate OpenAPI documentation and type-safe HTTP handling, and want both derived from the same source of truth.
Avoid When
Your team prefers writing OpenAPI specs manually (spec-first), or you're using a non-Scala JVM language where the type system benefits are reduced.
Use Cases
- • Define typed agent API endpoints once and generate both http4s server routes and OpenAPI 3.0 documentation automatically without manual spec maintenance
- • Build type-safe Scala HTTP clients from the same endpoint definitions used for the server — guarantees client and server API contracts stay in sync
- • Generate validated API documentation for agent services that is always accurate because it derives from the same type definitions as the implementation
- • Implement contract-first API development in Scala — define endpoints as typed values, then implement handler logic separately
- • Add automatic request/response validation by leveraging Tapir's codec derivation — invalid inputs are rejected before reaching business logic
Not For
- • Non-Scala teams — Tapir is Scala-specific; use OpenAPI Generator for multi-language spec-first development
- • Simple APIs without OpenAPI documentation needs — direct http4s or Akka HTTP routes are simpler without Tapir's endpoint abstraction
- • Teams that prefer handwriting OpenAPI specs — Tapir generates specs from code; code-first approach only
Interface
Authentication
Tapir provides endpoint.securityIn for modeling auth (bearer token, API key, basic auth) as typed inputs. Actual auth validation is server-side logic.
Pricing
Tapir is Apache 2.0 licensed, maintained by SoftwareMill. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Endpoint definitions use type-level programming — complex endpoint types cause slow Scala compilation; split complex endpoints into multiple simpler ones and combine with .orElse
- ⚠ Server interpreter selection is explicit — tapir-http4s-server, tapir-akka-http-server, tapir-zio-http-server are separate artifacts; importing the wrong interpreter causes runtime route failures
- ⚠ Error outputs must be explicitly defined — Tapir only generates error responses that are specified in .errorOut(); uncaught exceptions propagate as 500s without documentation
- ⚠ Streaming endpoints require explicit stream type parameters — streaming JSON arrays or server-sent events need fs2.Stream or akka.stream.scaladsl.Source typed endpoints
- ⚠ OpenAPI docs generation is separate from server — tapir-openapi-docs is a separate artifact; forgetting to add it means no OpenAPI spec even though endpoint types are defined
- ⚠ Binary backwards compatibility — Tapir uses Scala version-dependent binary artifacts (tapir-core_2.13, tapir-core_3); ensure Scala version consistency across all tapir modules in the project
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Tapir.
Scores are editorial opinions as of 2026-03-06.