tapir

Rapid development of self-documenting APIs

Intro

Tapir is a library to describe HTTP APIs, expose them as a server, consume as a client, and automatically document using open standards.

Tapir is fast and developer-friendly. The endpoint definition APIs are crafted with readability and discoverability in mind. Our Netty-based server is one of the best-performing Scala HTTP servers available.

endpoint
  .get.in("hello").in(query[String]("name"))
  .out(stringBody)
  .handleSuccess(name => s"Hello, $name!")

Tapir integrates with all major Scala stacks, so you can use your favorite approach to Functional Programming, while leveraging all the benefits that Tapir brings!

Seamless integration with the Scala and HTTP ecosystems is one of Tapir’s major strengths:

all popular Scala HTTP server implementations are supported. You can define your entire API using Tapir, or expose Tapir-managed routes alongside “native” ones. This is especially useful when gradually adopting Tapir, or using it for selected use-cases.
the Scala ecosystem is rich with libraries leveraging its type-safety and enhancing the developer’s toolbox, that’s why Tapir provides integrations with many of such custom type, JSON and observability libraries
documentation can be generated in the OpenAPI, AsyncAPI and JSON Schema formats

Depending on how you’d prefer to explore Tapir, this documentation has three main sections:

There’s a number of tutorials, which provide a gentle introduction to the library
Nothing compares to tinkering with working code, that’s why we’ve prepared runnable examples, covering solutions to many “everyday” problems
Finally, the reference documentation describes all of Tapir’s aspects in depth - take a look at the menu on the left, starting with the “Endpoints” section

ScalaDocs are available at javadoc.io.

Tapir is licensed under Apache2, the source code is available on GitHub.

Why tapir?

type-safety: compile-time guarantees, develop-time completions, read-time information
declarative: separate the shape of the endpoint (the “what”), from the server logic (the “how”)
OpenAPI / Swagger integration: generate documentation from endpoint descriptions
observability: leverage the metadata to report rich metrics and tracing information
abstraction: re-use common endpoint definitions, as well as individual inputs/outputs
library, not a framework: integrates with your stack

Code teaser

import sttp.tapir.*
import sttp.tapir.generic.auto.*
import sttp.tapir.json.circe.*
import io.circe.generic.auto.*

type Limit = Int
type AuthToken = String
case class BooksQuery(genre: String, year: Int)
case class Book(title: String)


// Define an endpoint

val booksListing: PublicEndpoint[(BooksQuery, Limit, AuthToken), String, List[Book], Any] =
  endpoint
    .get
    .in(("books" / path[String]("genre") / path[Int]("year")).mapTo[BooksQuery])
    .in(query[Limit]("limit").description("Maximum number of books to retrieve"))
    .in(header[AuthToken]("X-Auth-Token"))
    .errorOut(stringBody)
    .out(jsonBody[List[Book]])


// Generate OpenAPI documentation

import sttp.apispec.openapi.circe.yaml.*
import sttp.tapir.docs.openapi.OpenAPIDocsInterpreter

val docs = OpenAPIDocsInterpreter().toOpenAPI(booksListing, "My Bookshop", "1.0")
println(docs.toYaml)


// Convert to pekko-http Route

import sttp.tapir.server.pekkohttp.PekkoHttpServerInterpreter
import org.apache.pekko.http.scaladsl.server.Route
import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

def bookListingLogic(bfy: BooksQuery,
                     limit: Limit,
                     at: AuthToken): Future[Either[String, List[Book]]] =
  Future.successful(Right(List(Book("The Sorrows of Young Werther"))))

val booksListingRoute: Route = PekkoHttpServerInterpreter()
  .toRoute(booksListing.serverLogic((bookListingLogic _).tupled))


// Convert to sttp Request

import sttp.tapir.client.sttp.SttpClientInterpreter
import sttp.client3.*

val booksListingRequest: Request[DecodeResult[Either[String, List[Book]]], Any] =
  SttpClientInterpreter()
    .toRequest(booksListing, Some(uri"http://localhost:8080"))
    .apply((BooksQuery("SF", 2016), 20, "xyz-abc-123"))

Other sttp projects

sttp is a family of Scala HTTP-related projects, and currently includes:

sttp client: the Scala HTTP client you always wanted!
sttp tapir: this project
sttp model: simple HTTP model classes (used by client & tapir)
sttp shared: shared web socket, FP abstractions, capabilities and streaming code.
sttp apispec: OpenAPI, AsyncAPI and JSON Schema models.

Table of contents

Getting started

Tutorials

Endpoints

Server interpreters

Client interpreters

Documentation interpreters

Testing

Testing

Generators

Generate endpoint definitions from an OpenAPI YAML
- Installation steps
- Usage and options