Docs: usage examples

3 files changed, 105 insertions, 6 deletions

diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000..397be22
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,96 @@
+.. _usage_examples:
+
+Usage examples
+==============
+
+POST a form using the synchronous backend
+-----------------------------------------
+
+Required dependencies::
+
+  libraryDependencies ++= List("com.softwaremill.sttp" %% "core" % "1.0.6")
+
+Example code::
+
+  import com.softwaremill.sttp._
+
+  val signup = Some("yes")
+
+  val request = sttp
+    // send the body as form data (x-www-form-urlencoded)
+    .body(Map("name" -> "John", "surname" -> "doe"))
+    // use an optional parameter in the URI
+    .post(uri"https://httpbin.org/post?signup=$signup")
+
+  implicit val backend = HttpURLConnectionBackend()
+  val response = request.send()
+
+  println(response.body)
+  println(response.headers)
+
+GET and parse JSON using the akka-http backend and json4s
+---------------------------------------------------------
+
+Required dependencies::
+
+  libraryDependencies ++= List(
+    "com.softwaremill.sttp" %% "akka-http-backend" % "1.0.6",
+    "com.softwaremill.sttp" %% "json4s" % "1.0.6"
+  )
+
+Example code::
+
+  import com.softwaremill.sttp._
+  import com.softwaremill.sttp.akkahttp._
+  import com.softwaremill.sttp.json4s._
+
+  import scala.concurrent.ExecutionContext.Implicits.global
+
+  case class HttpBinResponse(origin: String, headers: Map[String, String])
+
+  val request = sttp
+    .get(uri"https://httpbin.org/get")
+    .response(asJson[HttpBinResponse])
+
+  implicit val backend = AkkaHttpBackend()
+  val response: Future[Response[HttpBinResponse]] = request.send()
+
+  for {
+    r <- response
+  } {
+    println(s"Got response code: ${r.code}")
+    println(r.body)
+    backend.close()
+  }
+
+Test an endpoint requiring multiple parameters
+----------------------------------------------
+
+Required dependencies::
+
+  libraryDependencies ++= List("com.softwaremill.sttp" %% "core" % "1.0.6")
+
+Example code::
+
+  import com.softwaremill.sttp._
+  import com.softwaremill.sttp.testing._
+
+  implicit val backend = SttpBackendStub.synchronous
+    .whenRequestMatches(_.uri.paramsMap.contains("filter"))
+    .thenRespond("Filtered")
+    .whenRequestMatches(_.uri.path.contains("secret"))
+    .thenRespond("42")
+
+  val parameters1 = Map("filter" -> "name=mary", "sort" -> "asc")
+  println(
+    sttp
+      .get(uri"http://example.org?search=true&$parameters1")
+      .send()
+      .unsafeBody)
+
+  val parameters2 = Map("sort" -> "desc")
+  println(
+    sttp
+      .get(uri"http://example.org/secret/read?$parameters2")
+      .send()
+      .unsafeBody)
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 1e0af24..b09389d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -25,7 +25,7 @@ Here's a very quick example of sttp in action::
   // response.unsafeBody: by default read into a String 
   println(response.unsafeBody)                     
 
-For more details, explore the subjects below!
+For more examples, see the :ref:`usage examples <usage_examples>` section. Or explore the features in detail:
 
 .. toctree::
    :maxdepth: 2
@@ -34,6 +34,7 @@ For more details, explore the subjects below!
    quickstart
    goals
    community             
+   examples
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/json.rst b/docs/json.rst
index f74e086..ea8e7d2 100644
--- a/docs/json.rst
+++ b/docs/json.rst
@@ -20,14 +20,14 @@ This module adds a method to the request and a function that can be given to a r
   implicit val backend = HttpURLConnectionBackend()
   
   // Assume that there is an implicit circe encoder in scope
-  // for the request Payload, and a decoder for the Response
+  // for the request Payload, and a decoder for the MyResponse
   val requestPayload: Payload = ???
   
-  val response: Either[io.circe.Error, Response] = 
+  val response: Either[io.circe.Error, MyResponse] =
     sttp
       .post(uri"...")
       .body(requestPayload)
-      .response(asJson[Response])
+      .response(asJson[MyResponse])
       .send()
 
 Json4s
@@ -47,12 +47,14 @@ Usage example::
   implicit val backend = HttpURLConnectionBackend()
 
   case class Payload(...)
+  case class MyResponse(...)
+
   val requestPayload: Payload = Payload(...)
   
-  val response: Response[Payload] = 
+  val response: Response[MyResponse] =
     sttp
       .post(uri"...")
       .body(requestPayload)
-      .response(asJson[Response])
+      .response(asJson[MyResponse])
       .send()