Running as an akka-http server¶
To expose an endpoint as an akka-http server, first add the following dependency:
"com.softwaremill.tapir" %% "tapir-akka-http-server" % "0.2"
and import the package:
import tapir.server.akkahttp._
This adds two extension methods to the Endpoint
type: toDirective
and toRoute
. Both require the logic of the
endpoint to be given as a function of type:
[I as function arguments] => Future[Either[E, O]]
Note that the function doesn’t take the tuple I
directly as input, but instead this is converted to a function of the
appropriate arity. For example:
import tapir._
import tapir.server.akkahttp._
import scala.concurrent.Future
import akka.http.scaladsl.server.Route
def countCharacters(s: String): Future[Either[Unit, Int]] =
Future.successful(Right[Unit, Int](s.length))
val countCharactersEndpoint: Endpoint[String, Unit, Int, Nothing] =
endpoint.in(stringBody).out(plainBody[Int])
val countCharactersRoute: Route = countCharactersEndpoint.toRoute(countCharacters _)
The created Route
/Directive
can then be further combined with other akka-http directives, for example nested within
other routes. The Tapir-generated Route
/Directive
captures from the request only what is described by the endpoint.
It’s completely feasible that some part of the input is read using akka-http directives, and the rest using tapir endpoint descriptions; or, that the tapir-generated route is wrapped in e.g. a metrics route. Moreover, “edge-case endpoints”, which require some special logic not expressible using tapir, can be always implemented directly using akka-http. For example:
val myRoute: Route = metricsDirective {
securityDirective { user =>
tapirEndpoint.toRoute(input => /* here we can use both `user` and `input` values */)
}
}
Streaming¶
The akka-http interpreter accepts streaming bodies of type Source[ByteString, Any]
, which can be used both for sending
response bodies and reading request bodies. Usage: streamBody[Source[ByteString, Any]](schema, mediaType)
.
Configuration¶
The interpreter can be configured by providing an implicit AkkaHttpServerOptions
value and status mappers, see
common server configuration for details.