-
Notifications
You must be signed in to change notification settings - Fork 422
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
29 changed files
with
555 additions
and
447 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # Using as an http4s client | ||
|
|
||
| Add the dependency: | ||
|
|
||
| ```scala | ||
| "com.softwaremill.sttp.tapir" %% "tapir-http4s-client" % "0.18.0-M1" | ||
| ``` | ||
|
|
||
| To interpret an endpoint definition as an `org.http4s.Request[F]`, import: | ||
|
|
||
| ```scala | ||
| import sttp.tapir.client.http4s.Http4sClientInterpreter | ||
| ``` | ||
|
|
||
| This objects contains two methods: | ||
| - `toRequestUnsafe(Endpoint, Option[String])`: given the optional base URI, returns a function | ||
| which generates a request and a response parser from endpoint inputs. Response parser throws | ||
| an exception if decoding of the result fails. | ||
| ```scala | ||
| I => (org.http4s.Request[F], org.http4s.Response[F] => F[Either[E, O]]) | ||
| ``` | ||
| - `toRequest(Endpoint, Option[String])`: given the optional base URI, returns a function | ||
| which generates a request and a response parser from endpoint inputs. Response parser | ||
| returns an instance of `DecodeResult` which contains the decoded response body or error details. | ||
| ```scala | ||
| I => (org.http4s.Request[F], org.http4s.Response[F] => F[DecodeResult[Either[E, O]]]) | ||
| ``` | ||
|
|
||
| Note that the returned functions have one-argument: the input values of end endpoint. This might be a | ||
| single type, a tuple, or a case class, depending on the endpoint description. | ||
|
|
||
| After providing the input parameters, the following values are returned: | ||
| - An instance of `org.http4s.Request[F]` with the input value | ||
| encoded as appropriate request parameters: path, query, headers and body. | ||
| The request can be further customised and sent using an http4s client, or run against `org.http4s.HttpRoutes[F]`. | ||
| - A response parser to be applied to the response received after executing the request. | ||
| The result will then contain the decoded error or success values | ||
| (note that this can be the body enriched with data from headers/status code). | ||
|
|
||
| See the [runnable example](https://github.com/softwaremill/tapir/blob/master/examples/src/main/scala/sttp/tapir/examples/Http4sClientExample.scala) | ||
| for example usage. | ||
|
|
||
| ## Limitations | ||
|
|
||
| - Multipart requests are not supported yet. | ||
| - WebSockets are not supported yet. | ||
| - Streaming capabilities: | ||
| - only `Fs2Streams` are supported at the moment. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # Content type | ||
|
|
||
| The endpoint's output content type is bound to the body outputs, that are specified for the endpoint (if any). The | ||
| [codec](codecs.md) of a body output contains a `CodecFormat`, which in turns contains the `MediaType` instance. | ||
|
|
||
| ## Codec formats and server interpreters | ||
|
|
||
| Codec formats define the *default* media type, which will be set as the `Content-Type` header. However, any | ||
| user-provided value will override this default: | ||
|
|
||
| * dynamic content type, using `.out(header(HeaderNames.ContentType))` | ||
| * fixed content type, using e.g. `out(header(Header.contentType(MediaType.ApplicationJson)))` | ||
|
|
||
| ## Multiple content types | ||
|
|
||
| Multiple, alternative content types can be specified using `oneOf`, similarly as when specifying [status code](statuscodes.md) | ||
| mappings. | ||
|
|
||
| On the server side, the appropriate mapping will be chosen using content negotiation, via the `Accept` header, using | ||
| the [configurable](../server/options.md) `ContentTypeInterceptor`. Note that both the base media type, and the charset | ||
| for text types are taken into account. | ||
|
|
||
| On the client side, the appropriate mapping will be chosen basing on the `Content-Type` header value. | ||
|
|
||
| For example: | ||
|
|
||
| ```scala | ||
| import sttp.tapir._ | ||
| import sttp.tapir.Codec.{JsonCodec, XmlCodec} | ||
| import sttp.model.StatusCode | ||
|
|
||
| case class Entity(name: String) | ||
| implicit val jsonCodecForOrganization: JsonCodec[Entity] = ??? | ||
| implicit val xmlCodecForOrganization: XmlCodec[Entity] = ??? | ||
|
|
||
| endpoint.out( | ||
| oneOf( | ||
| oneOfMapping(StatusCode.Ok, anyJsonBody[Entity]), | ||
| oneOfMapping(StatusCode.Ok, xmlBody[Entity]), | ||
| ) | ||
| ) | ||
| ``` | ||
|
|
||
| For details on how to create codes manually or derive them automatically, see [custom types](customtypes.md) and the | ||
| subsequent section on json. | ||
|
|
||
| ## Next | ||
|
|
||
| Read on about [json support](json.md). |
Oops, something went wrong.