Merge pull request #19797 from ktoso/wip-entity-raw-json-ktoso

+doc #19796 explain how to obtain a JsValue using entity(as)

akka-docs/rst/scala/code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala

@@ -8,7 +8,7 @@ import akka.http.scaladsl.marshallers.sprayjson.SprayJsonSupport
 import docs.http.scaladsl.server.RoutingSpec
 import akka.http.scaladsl.model.MediaTypes.`application/json`
 import akka.http.scaladsl.model._
-import spray.json.DefaultJsonProtocol
+import spray.json.{ JsValue, DefaultJsonProtocol }
 
 //# person-case-class
 case class Person(name: String, favoriteNumber: Int)
@@ -37,6 +37,22 @@ class MarshallingDirectivesExamplesSpec extends RoutingSpec {
       }
   }
 
+  "example-entity-with-raw-json" in {
+    import PersonJsonSupport._
+
+    val route = post {
+      entity(as[JsValue]) { json =>
+        complete(s"Person: ${json.asJsObject.fields("name")} - favorite number: ${json.asJsObject.fields("favoriteNumber")}")
+      }
+    }
+
+    // tests:
+    Post("/", HttpEntity(`application/json`, """{ "name": "Jane", "favoriteNumber" : 42 }""")) ~>
+      route ~> check {
+        responseAs[String] shouldEqual """Person: "Jane" - favorite number: 42"""
+      }
+  }
+
   "example-completeWith-with-json" in {
     import PersonJsonSupport._
 

akka-docs/rst/scala/http/routing-dsl/directives/marshalling-directives/entity.rst

@@ -49,3 +49,11 @@ class.  It utilizes ``SprayJsonSupport`` via the ``PersonJsonSupport`` object as
 .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
    :snippet: example-entity-with-json
 
+It is also possible to use the ``entity`` directive to obtain raw ``JsValue`` ( spray-json_ ) objects, by simply using
+``as[JsValue]``, or any other JSON type for which you have marshallers in-scope.
+
+.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/MarshallingDirectivesExamplesSpec.scala
+   :snippet: example-entity-with-raw-json
+
+
+.. _spray-json: https://github.com/spray/spray-json