With tapir you can describe HTTP API endpoints as immutable Scala values. Each endpoint can contain a number of input parameters, error-output parameters, and normal-output parameters. An endpoint specification can be interpreted as:
- a server, given the "business logic": a function, which computes output parameters based on input parameters. Currently supported:
- a client, which is a function from input parameters to output parameters. Currently supported: sttp.
- documentation. Currently supported: OpenAPI.
Tapir is licensed under Apache2, the source code is available of GitHub.
import tapir._
import tapir.json.circe._
import io.circe.generic.auto._
type Limit = Int
type AuthToken = String
case class BooksFromYear(genre: String, year: Int)
case class Book(title: String)
val booksListing: Endpoint[(BooksFromYear, Limit, AuthToken), String, List[Book], Nothing] =
endpoint
.get
.in(("books" / path[String]("genre") / path[Int]("year")).mapTo(BooksFromYear))
.in(query[Limit]("limit").description("Maximum number of books to retrieve"))
.in(header[AuthToken]("X-Auth-Token"))
.errorOut(stringBody)
.out(jsonBody[List[Book]])
//
import tapir.docs.openapi._
import tapir.openapi.circe.yaml._
val docs = booksListing.toOpenAPI("My Bookshop", "1.0")
println(docs.toYaml)
//
import tapir.server.akkahttp._
import akka.http.scaladsl.server.Route
import scala.concurrent.Future
def bookListingLogic(bfy: BooksFromYear,
limit: Limit,
at: AuthToken): Future[Either[String, List[Book]]] =
Future.successful(Right(List(Book("The Sorrows of Young Werther"))))
val booksListingRoute: Route = booksListing.toRoute(bookListingLogic _)
//
import tapir.client.sttp._
import com.softwaremill.sttp._
val booksListingRequest: Request[Either[String, List[Book]], Nothing] = booksListing
.toSttpRequest(uri"http://localhost:8080")
.apply(BooksFromYear("SF", 2016), 20, "xyz-abc-123")
Also check out the runnable example which is a slight extension of the above.
- Quickstart
- Goals of the project
- Endpoints: basics
- Endpoints: inputs/outputs
- Endpoints: codecs
- Endpoints: working with JSON
- Endpoints: forms
- Endpoints: authentication
- Endpoints: implicits guide
- Servers: akka-http interpreter
- Servers: http4s interpreter
- Servers: common
- Servers: debugging
- Clients: sttp interpreter
- Documentation: openapi interpreter
- Create your own tapir
- Contributing