Update documentation

README.md

@@ -14,7 +14,10 @@ interpreted as:
   * [Http4s](https://tapir.softwaremill.com/en/latest/server/http4s.html) `HttpRoutes[F]`
   * [Finatra](https://tapir.softwaremill.com/en/latest/server/finatra.html) `FinatraRoute`
   * [Play](https://tapir.softwaremill.com/en/latest/server/play.html) `Route`
-* a client, which is a function from input parameters to output parameters. Currently supported: [sttp](https://tapir.softwaremill.com/en/latest/sttp.html).
+* a client, which is a function from input parameters to output parameters.
+  Currently supported:
+  * [sttp](https://tapir.softwaremill.com/en/latest/client/sttp.html).
+  * [Play](https://tapir.softwaremill.com/en/latest/client/play.html).
 * documentation. Currently supported: 
   * [OpenAPI](https://tapir.softwaremill.com/en/latest/docs/openapi.html)
   * [AsyncAPI](https://tapir.softwaremill.com/en/latest/docs/asyncapi.html)

doc/client/play.md

@@ -0,0 +1,60 @@
+# Using as a Play client
+
+Add the dependency:
+
+```scala
+"com.softwaremill.sttp.tapir" %% "tapir-play-client" % "@VERSION@"
+```
+
+To make requests using an endpoint definition using the [play client](https://github.com/playframework/play-ws), import:
+
+```scala mdoc:compile-only
+import sttp.tapir.client.play._
+```
+
+This adds the two extension methods to any `Endpoint`:
+ - `toPlayRequestUnsafe(String)`: given the base URI returns a function,
+   which will generate a request and a response parser which might throw
+   an exception when decoding of the result fails
+   ```scala
+   I => (StandaloneWSRequest, StandaloneWSResponse => Either[E, O])
+   ```
+ - `toPlayRequest(String)`: given the base URI returns a function,
+   which will generate a request and a response parser which represents
+   decoding errors as the `DecodeResult` class
+   ```scala
+   I => (StandaloneWSRequest, StandaloneWSResponse => DecodeResult[Either[E, O]])
+   ```
+
+Note that these are a one-argument functions, where the single argument is the input 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 two following are returned:
+- a description of the request to be made, with the input value
+  encoded as appropriate request parameters: path, query, headers and body.
+  This can be further customised and sent using regular Play methods.
+- a response parser to be applied to the response got 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).
+
+Example:
+
+```scala mdoc:compile-only
+val e: Endpoint[I, E, O, S] = ???
+val inputArgs: I = ???
+
+val (req, responseParser) = e
+    .toPlayRequestUnsafe(s"http://localhost:9000")
+    .apply(inputArgs)
+
+val result: Future[Either[E, O]] = req
+    .execute()
+    .map(responseParser)
+```
+
+## Limitations
+
+Multipart requests are not supported.
+
+Streaming capabilities:
+- only `AkkaStreams` is supported

doc/endpoint/basics.md

@@ -45,7 +45,7 @@ You can think of an endpoint as a function, which takes input parameters of type
 Note that the empty `endpoint` description maps no values to either error and success outputs, however errors
 are still represented and allowed to occur. If you would prefer to use an endpoint description, where
 errors can not happen, use `infallibleEndpoint: Endpoint[Unit, Nothing, Unit, Nothing]`. This might be useful when
-interpreting endpoints [as a client](../sttp.md).
+interpreting endpoints [as a client](../client/sttp.md).
 
 ## Defining an endpoint
 

doc/index.md

@@ -9,7 +9,11 @@ interpreted as:
   * [Akka HTTP](server/akkahttp.md) `Route`s/`Directive`s.
   * [Http4s](server/http4s.md) `HttpRoutes[F]`
   * [Finatra](server/finatra.md) `http.Controller`
-* a client, which is a function from input parameters to output parameters. Currently supported: [sttp](sttp.md).
+  * [Play](server/play.md) `Route`
+* a client, which is a function from input parameters to output parameters.
+  Currently supported:
+  * [sttp](client/sttp.md).
+  * [Play](client/play.md).
 * documentation. Currently supported: :
   * [OpenAPI](docs/openapi.md).
   * [AsyncAPI](docs/asyncapi.md).
@@ -137,7 +141,8 @@ Development and maintenance of sttp tapir is sponsored by [SoftwareMill](https:/
    :maxdepth: 2
    :caption: Client interpreters
    
-   sttp
+   client/sttp
+   client/play
 
 .. toctree::
    :maxdepth: 2