Examples by category

The Tapir repository contains a number of how-to guides. If you’re missing an example for your use-case, please let us know by reporting an issue!

Each example is fully self-contained and can be run using scala-cli (you just need to copy the content of the file, apart from scala-cli, no additional setup is required!). Hopefully this will make experimenting with Tapir as frictionless as possible!

Examples are tagged with the stack being used (Direct-style, cats-effect, ZIO, Future), server implementation, generated documentation format etc.

Hello, World!

• A demo of Tapir’s capabilities circe sttp4 Swagger UI Future Pekko HTTP

• A demo of Tapir’s capabilities Pickler sttp4 Swagger UI Future Netty

• Exposing an endpoint using the Armeria server Future Armeria

• Exposing an endpoint using the Netty server (Direct-style variant) Direct Netty

• Exposing an endpoint using the Netty server (Future variant) Future Netty

• Exposing an endpoint using the Netty server (cats-effect variant) cats-effect Netty

• Exposing an endpoint using the Pekko HTTP server Future Pekko HTTP

• Exposing an endpoint using the ZIO HTTP server ZIO ZIO JSON ZIO HTTP

• Exposing an endpoint using the ZIO HTTP server Swagger UI ZIO circe ZIO HTTP

• Exposing an endpoint using the built-in JDK HTTP server Direct JDK Http

• Exposing an endpoint using the http4s server cats-effect http4s

• Exposing an endpoint using the http4s server Swagger UI ZIO circe http4s

• Exposing an endpoint, defined with ZIO and depending on services in the environment, using the http4s server Swagger UI ZIO circe http4s

• Extending a base endpoint (which has the security logic provided), with server logic ZIO http4s

Client interpreter

• Interpreting an endpoint as an http4s client circe cats-effect

Custom types

• A demo of Tapir’s capabilities using semi-auto derivation circe sttp4 Swagger UI Future Pekko HTTP

• A query parameter which maps to a Scala 3 enum (enumeration) Direct Netty

• Handling comma-separated query parameters Swagger UI Direct Netty

• Mapping a sealed trait hierarchy to JSON using a discriminator circe Swagger UI Direct Netty

• Supporting custom types, when used in query or path parameters, as well as part of JSON bodies circe

Error handling

• Customising errors that are reported on decode failures (e.g. invalid or missing query parameter) Future Pekko HTTP

• Default error handler returning errors as JSON Future circe Pekko HTTP

• Error and successful outputs Future circe Pekko HTTP

• Error reporting provided by Iron type refinements circe cats-effect Netty

• Extending a base secured endpoint with error variants, using union types circe cats-effect http4s

• Optional returned from the server logic, resulting in 404 if None circe Future Pekko HTTP

JSON

• Receive JSON, parse it in a streaming way, expose documentation jsoniter Swagger UI Direct Netty

• Return a JSON body which optionally serializes as null circe Direct Netty

• Return a JSON response with Circe and auto-dervied codecs circe Direct Netty

• Return a JSON response with Jsoniter jsoniter Direct Netty

Logging

• Logging using a correlation id ZIO Netty

Multipart

• Uploading a multipart form, with text and file parts Future Pekko HTTP

Observability

• OpenTelemetry tracing interceptor Direct circe Netty

• Otel4s collecting metrics cats-effect circe Netty

• Otel4s collecting traces cats-effect circe Netty

• Reporting DataDog metrics Future circe Netty

• Reporting OpenTelemetry metrics Future circe Netty

• Reporting Prometheus metrics ZIO ZIO HTTP

• Reporting Prometheus metrics Future circe Netty

OpenAPI documentation

• Adding OpenAPI documentation extensions circe

• Documenting multiple endpoints Swagger UI cats-effect circe http4s

• Documenting multiple endpoints Swagger UI Future circe Pekko HTTP

• Exposing documentation using ReDoc ReDoc ZIO circe ZIO HTTP

• Exposing documentation using ReDoc ReDoc cats-effect http4s

• Securing Swagger UI using OAuth 2 Swagger UI Future Pekko HTTP

Schemas

• Customising a derived schema, using annotations, and using implicits Swagger UI Future circe Netty

Security

• CORS interceptor Future Pekko HTTP

• CORS interceptor Future Vert.x

• HTTP basic authentication Future Pekko HTTP

• Interceptor verifying externally added security credentials Future Netty

• Login using OAuth2, authorization code flow cats-effect circe http4s

• Securing endpoint with CSRF tokens example Future Netty

• Separating security and server logic, with a reusable base endpoint Future Pekko HTTP

• Separating security and server logic, with a reusable base endpoint, accepting & refreshing credentials via cookies Future Pekko HTTP

• Separating security and server logic, with a reusable base endpoint, accepting & refreshing credentials via cookies ZIO ZIO HTTP

Server Sent Events

• Describe and implement an endpoint which emits SSE Direct Netty

• Respond with either SSE or JSON Direct Netty

Static content

• Serving static files from a directory Direct Netty

• Serving static files from a directory, with range requests Future Pekko HTTP

• Serving static files from resources Future Pekko HTTP

• Serving static files secured with a bearer token Future Pekko HTTP

Status code

• Responding with fixed or dynamic status code Direct Netty

Streaming

• Proxy requests, handling bodies as fs2 streams cats-effect http4s

• Respond with an fs2 stream, or with an error, represented as a failed effect in the business logic cats-effect http4s

• Stream response as a Pekko stream Future Pekko HTTP

• Stream response as a ZIO stream ZIO Netty

• Stream response as a ZIO stream ZIO ZIO HTTP

• Stream response as an fs2 stream cats-effect http4s

• Stream response as an fs2 stream cats-effect Netty

Testing

• Test endpoints using the MockServer client circe

• Test endpoints using the TapirStubInterpreter cats-effect

• Test endpoints using the TapirStubInterpreter Future Pekko HTTP

WebSocket

• A WebSocket chat across multiple clients connected to the same server Direct Netty

• Describe and implement a WebSocket endpoint Direct Netty

• Describe and implement a WebSocket endpoint Future Pekko HTTP

• Describe and implement a WebSocket endpoint AsyncAPI cats-effect circe http4s

• Describe and implement a WebSocket endpoint, accepting and returning JSON messages ZIO ZIO JSON ZIO HTTP

• Describe and implement a WebSocket endpoint, being notified on the server-side that a client closed the socket, using a custom codec ZIO ZIO HTTP