diff --git a/doc/endpoint/basics.md b/doc/endpoint/basics.md index 98eaa222f0..e67d1483bc 100644 --- a/doc/endpoint/basics.md +++ b/doc/endpoint/basics.md @@ -30,7 +30,7 @@ import sttp.tapir._ type PublicEndpoint[I, E, O, -R] = Endpoint[Unit, I, E, O, R] ``` -A public endpoint has two inputs of types `UUID` and `Int`, upon error returns a `String`, and on normal +A public endpoint that has two inputs of types `UUID` and `Int`, upon error returns a `String`, and on normal completion returns a `User`, would have the type: ```scala mdoc:invisible @@ -45,7 +45,7 @@ import sttp.tapir._ val userEndpoint: PublicEndpoint[(UUID, Int), String, User, Any] = ??? ``` -You can think of an endpoint as a function, which takes input parameters of type `A` and `I` and returns a result of type +You can think of an endpoint as a function which takes input parameters of type `A` and `I` and returns a result of type `Either[E, O]`. ### Infallible endpoints @@ -54,7 +54,7 @@ Note that the empty `endpoint` description maps no values to either error and su are still represented and allowed to occur. In case of the error output, the single member of the unit type, `(): Unit`, maps to an empty-body `400 Bad Request`. -If you prefer to use an endpoint description, where errors cannot happen, use +If you prefer to use an endpoint description where errors cannot happen use `infallibleEndpoint: PublicEndpoint[Unit, Nothing, Unit, Any]`. This might be useful when interpreting endpoints [as a client](../client/sttp.md). diff --git a/doc/endpoint/codecs.md b/doc/endpoint/codecs.md index b4a9cd303a..5337dc3998 100644 --- a/doc/endpoint/codecs.md +++ b/doc/endpoint/codecs.md @@ -29,8 +29,8 @@ integer. If any of this fails, a decode failure will be reported. However, in some cases codecs aren't looked up as implicit values, instead being created from simpler components, which themselves are looked up as implicits. This is the case e.g. for json bodies specified using `jsonBody`. The rationale -behind such a design is that this provides better error reporting, in case the implicit components, used to create the -codec, are missing. Consult the signature of the specific input/output to learn what are its implicit requirements. +behind such a design is that this provides better error reporting, in case the implicit components used to create the +codec are missing. Consult the signature of the specific input/output to learn what are its implicit requirements. ## Decode failures diff --git a/doc/endpoint/customtypes.md b/doc/endpoint/customtypes.md index 5d76128001..de234052ce 100644 --- a/doc/endpoint/customtypes.md +++ b/doc/endpoint/customtypes.md @@ -36,7 +36,7 @@ information: * schema (for documentation and validation) * codec format (`text/plain`, `application/json` etc.) -This might be quite a lot of work, that's why it's usually easier to map over an existing codec. To do that, you'll +This might be quite a lot of work; that's why it's usually easier to map over an existing codec. To do that, you'll need to provide two mappings: * a `decode` method which decodes the lower-level type into the custom type, optionally reporting decode failures @@ -88,7 +88,7 @@ implicit val myIdCodec: PlainCodec[MyId] = Codec.string.mapDecode(decode)(encode usually better to define a codec for that type. ``` -Then, you can use the new codec e.g. to obtain an id from a query parameter, or a path segment: +Then, you can use the new codec; e.g. to obtain an id from a query parameter, or a path segment: ```scala mdoc:silent endpoint.in(query[MyId]("myId")) diff --git a/doc/endpoint/ios.md b/doc/endpoint/ios.md index 48de1b7dd3..e8e8b0ce8f 100644 --- a/doc/endpoint/ios.md +++ b/doc/endpoint/ios.md @@ -47,7 +47,7 @@ For outputs: Endpoint inputs/outputs can be combined in two ways. However they are combined, the values they represent always accumulate into tuples of values. -First, inputs/outputs can be combined using the `.and` method. Such a combination results in an input/output, which maps +First, inputs/outputs can be combined using the `.and` method. Such a combination results in an input/output which maps to a tuple of the given types. This combination can be assigned to a value and re-used in multiple endpoints. As all other values in tapir, endpoint input/output descriptions are immutable. For example, an input specifying two query parameters, `start` (mandatory) and `limit` (optional) can be written down as: diff --git a/doc/endpoint/oneof.md b/doc/endpoint/oneof.md index 2ee0f974d0..2d95db3cc5 100644 --- a/doc/endpoint/oneof.md +++ b/doc/endpoint/oneof.md @@ -11,7 +11,7 @@ Outputs with multiple variants can be specified using the `oneOf` output. Each v variant. All possible outputs must have a common supertype. Typically, the supertype is a sealed trait, and the variants are implementing case classes. -Each one-of variant needs an `appliesTo` function to determine at run-time, if the variant should be used for a given +Each one-of variant needs an `appliesTo` function to determine at run-time if the variant should be used for a given value. This function is inferred at compile time when using `oneOfVariant`, but can also be provided by hand, or if the compile-time inference fails, using one of the other factory methods (see below). A catch-all variant can be defined using `oneOfDefaultVariant`, and should be placed as the last variant in the list of possible variants. @@ -209,7 +209,7 @@ However, this makes it impossible to use streaming bodies in `oneOf` (via `oneOf require normal input/outputs as parameters. To bypass this limitation, a `.toEndpointIO` method is available on streaming bodies, which "lifts" them to an `EndpointIO` type, forgetting the streaming requirement. This decreases type safety, as a run-time error might occur if an incompatible interpreter is used, however allows describing -endpoints, which require including streaming bodies in output variants. +endpoints which require including streaming bodies in output variants. ```eval_rst .. note:: diff --git a/doc/endpoint/validation.md b/doc/endpoint/validation.md index a5615da040..22bfdc716d 100644 --- a/doc/endpoint/validation.md +++ b/doc/endpoint/validation.md @@ -62,8 +62,8 @@ implicit val myIdCodec: Codec[String, MyId, TextPlain] = Codec.string The validators are run when a value is being decoded from its low-level representation. This is done using the `Codec.decode` method, which returns a `DecodeResult`. Such a result can be successful, or a decoding failure. -Keep in mind, that the validator mechanism described here is meant for input/output values which are in an incorrect -low-level format. Validators and more generally decoding failures should be reported only for format failures. +Keep in mind that the validator mechanism described here is meant for input/output values which are in an incorrect +low-level format. Validation and more generally decoding failures should be reported only for format failures. Business validation errors, which are often contextual, should use the error output instead. To customise error messages that are returned upon validation/decode failures by the server, see @@ -91,7 +91,7 @@ converts the enum value to a raw type (typically a string). This can be specifie ### Enumerations in schemas/codecs -To simplify creation of schemas and codec, with a derived enum validator, `Schema.derivedEnumeration` and `Codec.derivedEnumeration` +To simplify creation of schemas and codec with a derived enum validator, `Schema.derivedEnumeration` and `Codec.derivedEnumeration` helper methods are available. For example: ```scala mdoc:silent:reset-object