=htc,doc #18535 improved docs on spray-json usage

akka-docs-dev/rst/scala/code/docs/http/scaladsl/SprayJsonExampleSpec.scala

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2009-2015 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.http.scaladsl
+
+import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport
+import akka.http.scaladsl.server.Directives
+import org.scalatest.{ Matchers, WordSpec }
+
+class SprayJsonExampleSpec extends WordSpec with Matchers {
+
+  "spray-json example" in {
+    //#example
+    import spray.json._
+
+    // domain model
+    final case class Item(name: String, id: Long)
+    final case class Order(items: List[Item])
+
+    // collect your json format instances into a support trait:
+    trait JsonSupport extends SprayJsonSupport with DefaultJsonProtocol {
+      implicit val itemFormat = jsonFormat2(Item)
+      implicit val orderFormat = jsonFormat1(Order) // contains List[Item]
+    }
+
+    // use it wherever json (un)marshalling is needed
+    class MyJsonService extends Directives with JsonSupport {
+
+      // format: OFF
+      val route =
+        get {
+          pathSingleSlash {
+            complete {
+              Item("thing", 42) // will render as JSON
+            }
+          }
+        } ~
+        post {
+          entity(as[Order]) { order => // will unmarshal JSON to Order
+            val itemsCount = order.items.size
+            val itemNames = order.items.map(_.name).mkString(", ")
+            complete(s"Ordered $itemsCount items: $itemNames")
+          }
+        }
+      // format: ON
+      //#
+    }
+  }
+}

akka-docs-dev/rst/scala/http/common/json-support.rst

@@ -21,7 +21,7 @@ that an implicit ``spray.json.RootJsonReader`` and/or ``spray.json.RootJsonWrite
 
 This is how you enable automatic support for (un)marshalling from and to JSON with `spray-json`_:
 
-1. Add a library dependency onto ``"com.typesafe.akka" %% "akka-http-spray-json-experimental" % "1.x"``.
+1. Add a library dependency onto ``"com.typesafe.akka" %% "akka-http-spray-json-experimental" % "@version@"``.
 
 2. ``import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport._`` or mix in the
    ``akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport`` trait.
@@ -31,6 +31,11 @@ This is how you enable automatic support for (un)marshalling from and to JSON wi
 
 Once you have done this (un)marshalling between JSON and your type ``T`` should work nicely and transparently.
 
+.. includecode:: ../../code/docs/http/scaladsl/SprayJsonExampleSpec.scala
+  :include: example
+
+To learn more about how spray-json works please refer to its `documentation <https://github.com/spray/spray-json>`_.
+
 
 .. _spray-json: https://github.com/spray/spray-json
 .. _SprayJsonSupport: @github@/akka-http-marshallers-scala/akka-http-spray-json/src/main/scala/akka/http/scaladsl/marshallers/sprayjson/SprayJsonSupport.scala