sttp.tapir

A bi-directional mapping between low-level values of type L and high-level values of type H. Low level values are formatted as CF.

The mapping consists of a pair of functions, one to decode (L => H), and one to encode (H => L) Decoding can fail, and this is represented as a result of type DecodeResult.

A codec also contains optional meta-data on the schema of the high-level value, as well as an instance of the format (which determines the media type of the low-level value).

Codec instances are used as implicit values, and are looked up when defining endpoint inputs/outputs. Depending on a particular endpoint input/output, it might require a codec which uses a specific format, or a specific low-level value.

Codec instances can be derived basing on other values (e.g. such as json encoders/decoders when integrating with json libraries). Or, they can be defined by hand for custom types, usually customising an existing, simpler codec.

Codecs can be chained with Mappings using the map function.

Specifies the format of the encoded values. Each variant must be a proper type so that it can be used as a discriminator for different (implicit) instances of Codec values.

A transput is EITHER an input, or an output (see: https://ell.stackexchange.com/questions/21405/hypernym-for-input-and-output). The transput traits contain common functionality, shared by all inputs and outputs.

Note that implementations of EndpointIO can be used BOTH as inputs and outputs.

The hierarchy is as follows:

                  /---> `EndpointInput`  >---\

EndpointTransput >--- ---> EndpointIO ---> EndpointOutput >---/

Lower-priority codec implicits, which transform other codecs. For example, when deriving a codec List[T] <-> Either[A, B], given codecs ca: T <-> A and cb: T <-> B, we want to get listHead(eitherRight(ca, cb)), not eitherRight(listHead(ca), listHead(cb)) (although they would function the same).

A bi-directional mapping between values of type L and values of type H.

Low-level values of type L can be decoded to a higher-level value of type H. The decoding can fail; this is represented by a result of type DecodeResult.Failure. Failures might occur due to format errors, wrong arity, exceptions, or validation errors. Validators can be added through the validate method.

High-level values of type H can be encoded as a low-level value of type L.

Mappings can be chained using one of the map functions.

Information needed to read a single part of a multipart body: the raw type (rawBodyType), and the codec which further decodes it.

The raw format of the body: what do we need to know, to read it and pass to a codec for further decoding.

Describes the type T: its low-level representation, meta-data and validation rules.

The type of the low-level representation of a T values. Part of Schemas.

Mixin containing aliases for top-level types and modules in the tapir package.

A body in any format, read using the given codec, from a raw string read using charset.

A body in any format, read using the given codec, from a raw string read using UTF-8.

Requires an implicit Codec.JsonCodec in scope. Such a codec can be created using Codec.json.

However, json codecs are usually derived from json-library-specific implicits. That's why integrations with various json libraries define jsonBody methods, which directly require the library-specific implicits.

Unless you have defined a custom json codec, the jsonBody methods should be used.

An empty output. Useful if one of the oneOf branches of a coproduct type is a case object that should be mapped to an empty body.

Extract a value from a server request. This input is only used by server interpreters, it is ignored by documentation interpreters and the provided value is discarded by client interpreters.

A server endpoint, which exposes a single file from local storage found at systemPath, using the given path.

fileServerEndpoint("static" / "hello.html")("/home/app/static/data.html")

A server endpoint, which exposes files from local storage found at systemPath, using the given prefix. Typically, the prefix is a path, but it can also contain other inputs. For example:

filesServerEndpoint("static" / "files")("/home/app/static")

A request to /static/files/css/styles.css will try to read the /home/app/static/css/styles.css file.

Specifies a correspondence between status codes and outputs.

All outputs must have a common supertype (T). Typically, the supertype is a sealed trait, and the mappings are implementing cases classes.

A single status code can have multiple mappings (or there can be multiple default mappings), with different body content types. The mapping can then be chosen based on content type negotiation, or the content type header.

Note that exhaustiveness of the mappings is not checked (that all subtypes of T are covered).

Create a fallback mapping to be used in oneOf output descriptions. Multiple such mappings can be specified, with different body content types.

Create a one-of-mapping which uses statusCode and output if the class of the provided value (when interpreting as a server) matches the runtime class of T.

This will fail at compile-time if the type erasure of T is different from T, as a runtime check in this situation would give invalid results. In such cases, use oneOfMappingClassMatcher, oneOfMappingValueMatcher or oneOfMappingFromMatchType instead.

Should be used in oneOf output descriptions.

Create a one-of-mapping which uses statusCode and output if the class of the provided value (when interpreting as a server) matches the given runtimeClass. Note that this does not take into account type erasure.

Should be used in oneOf output descriptions.

Create a one-of-mapping which uses statusCode and output if the provided value exactly matches one of the values provided in the second argument list.

Should be used in oneOf output descriptions.

Experimental!

Create a one-of-mapping which uses statusCode and output if the provided value matches the target type, as checked by MatchType. Instances of MatchType are automatically derived and recursively check that classes of all fields match, to bypass issues caused by type erasure.

Should be used in oneOf output descriptions.

Create a one-of-mapping which uses statusCode and output if the provided value (when interpreting as a server matches the matcher predicate.

Should be used in oneOf output descriptions.

A server endpoint, which exposes a single resource available from the given classLoader at resourcePath, using the given path.

resourceServerEndpoint("static" / "hello.html")(classOf[App].getClassLoader, "app/data.html")

A server endpoint, which exposes resources available from the given classLoader, using the given prefix. Typically, the prefix is a path, but it can also contain other inputs. For example:

resourcesServerEndpoint("static" / "files")(classOf[App].getClassLoader, "app")

A request to /static/files/css/styles.css will try to read the /app/css/styles.css resource.

Creates a stream body with a binary schema. The application/octet-stream media type will be used by default, but can be later overridden by providing a custom Content-Type header value.

Creates a stream body with a text schema.

Creates a stream body with a text schema.

Requires an implicit Codec.XmlCodec in scope. Such a codec can be created using Codec.xml.

An empty output. Useful if one of oneOf branches should be mapped to the status code only.