+doc,htp #18496 recoverRejections documented

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

@@ -10,7 +10,7 @@ import java.io.File
 import akka.event.Logging
 import akka.http.scaladsl.model._
 import akka.http.scaladsl.model.headers.RawHeader
-import akka.http.scaladsl.server.RouteResult.Rejected
+import akka.http.scaladsl.server.RouteResult.{ Complete, Rejected }
 import akka.http.scaladsl.server._
 import akka.stream.ActorMaterializer
 import akka.stream.io.SynchronousFileSource
@@ -248,6 +248,79 @@ class BasicDirectivesExamplesSpec extends RoutingSpec {
     Get("/") ~> route ~> check {
       rejection shouldEqual AuthorizationFailedRejection
     }
+
+    Get("/abc") ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+    }
+  }
+  "recoverRejections" in {
+    val authRejectionsToNothingToSeeHere = recoverRejections { rejections =>
+      if (rejections.exists(_.isInstanceOf[AuthenticationFailedRejection]))
+        Complete(HttpResponse(entity = "Nothing to see here, move along."))
+      else if (rejections == Nil) // see "Empty Rejections" for more details
+        Complete(HttpResponse(StatusCodes.NotFound, entity = "Literally nothing to see here."))
+      else
+        Rejected(rejections)
+    }
+    val neverAuth: Authenticator[String] = creds => None
+    val alwaysAuth: Authenticator[String] = creds => Some("id")
+
+    val route =
+      authRejectionsToNothingToSeeHere {
+        pathPrefix("auth") {
+          path("never") {
+            authenticateBasic("my-realm", neverAuth) { user =>
+              complete("Welcome to the bat-cave!")
+            }
+          } ~
+            path("always") {
+              authenticateBasic("my-realm", alwaysAuth) { user =>
+                complete("Welcome to the secret place!")
+              }
+            }
+        }
+      }
+
+    Get("/auth/never") ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+      responseAs[String] shouldEqual "Nothing to see here, move along."
+    }
+    Get("/auth/always") ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+      responseAs[String] shouldEqual "Welcome to the secret place!"
+    }
+    Get("/auth/does_not_exist") ~> route ~> check {
+      status shouldEqual StatusCodes.NotFound
+      responseAs[String] shouldEqual "Literally nothing to see here."
+    }
+  }
+  "recoverRejectionsWith" in {
+    val authRejectionsToNothingToSeeHere = recoverRejectionsWith { rejections =>
+      Future {
+        // imagine checking rejections takes a longer time:
+        if (rejections.exists(_.isInstanceOf[AuthenticationFailedRejection]))
+          Complete(HttpResponse(entity = "Nothing to see here, move along."))
+        else
+          Rejected(rejections)
+      }
+    }
+    val neverAuth: Authenticator[String] = creds => None
+
+    val route =
+      authRejectionsToNothingToSeeHere {
+        pathPrefix("auth") {
+          path("never") {
+            authenticateBasic("my-realm", neverAuth) { user =>
+              complete("Welcome to the bat-cave!")
+            }
+          }
+        }
+      }
+
+    Get("/auth/never") ~> route ~> check {
+      status shouldEqual StatusCodes.OK
+      responseAs[String] shouldEqual "Nothing to see here, move along."
+    }
   }
   "0mapRequest" in {
     def transformToPostRequest(req: HttpRequest): HttpRequest = req.copy(method = HttpMethods.POST)

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

@@ -69,7 +69,6 @@ class FileAndResourceDirectivesExamplesSpec extends RoutingSpec {
         getFromBrowseableDirectories("/main", "/backups")
       }
 
-
     Get("/tmp") ~> route ~> check {
       status shouldEqual StatusCodes.OK
     }

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

@@ -29,9 +29,9 @@ class FormFieldDirectivesExamplesSpec extends RoutingSpec {
       formField('color) { color =>
         complete(s"The color is '$color'")
       } ~
-      formField('id.as[Int]) { id =>
-        complete(s"The id is '$id'")
-      }
+        formField('id.as[Int]) { id =>
+          complete(s"The id is '$id'")
+        }
 
     Post("/", FormData("color" -> "blue")) ~> route ~> check {
       responseAs[String] shouldEqual "The color is 'blue'"

akka-docs-dev/rst/scala/http/routing-dsl/directives/alphabetically.rst

@@ -170,9 +170,9 @@ Directive                                   Description
                                             ``RequestContext``, without implicitly consuming a leading slash
 :ref:`-rawPathPrefixTest-`                  Checks whether the unmatchedPath has a prefix matched by the given
                                             ``PathMatcher``
-:ref:`-recoverRejections-`                  Transforms rejections from a previous route with an
+:ref:`-recoverRejections-`                  Transforms rejections from the inner route with an
                                             ``immutable.Seq[Rejection] ⇒ RouteResult`` function
-:ref:`-recoverRejectionsWith-`              Transforms rejections from a previous route with an
+:ref:`-recoverRejectionsWith-`              Transforms rejections from the inner route with an
                                             ``immutable.Seq[Rejection] ⇒ Future[RouteResult]`` function
 :ref:`-redirect-`                           Completes the request with redirection response of the given type to the
                                             given URI

akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/recoverRejections.rst

@@ -3,7 +3,7 @@
 recoverRejections
 =================
 
-...
+Transforms rejections from the inner route with an ``immutable.Seq[Rejection] ⇒ RouteResult`` function.
 
 Signature
 ---------
@@ -14,10 +14,17 @@ Signature
 Description
 -----------
 
-...
+**Low level directive** – unless you're sure you need to be working on this low-level you might instead
+want to try the :ref:`-handleRejections-` directive which provides a nicer DSL for building rejection handlers.
+
+Transforms rejections from the inner route to a ``RouteResult`` – either a ``Complete(HttpResponse(...))``
+or more rejections: ``Rejected(rejections)``.
+
+.. note::
+  To learn more about how and why rejections work read the :ref:`rejections-scala` section of the documentation.
 
 Example
 -------
 
 .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
-   :snippet: 0recoverRejections
+   :snippet: recoverRejections

akka-docs-dev/rst/scala/http/routing-dsl/directives/basic-directives/recoverRejectionsWith.rst

@@ -3,7 +3,9 @@
 recoverRejectionsWith
 =====================
 
-...
+Transforms rejections from the inner route with an ``immutable.Seq[Rejection] ⇒ Future[RouteResult]`` function.
+
+Asynchronous version of :ref:`-recoverRejections-`.
 
 Signature
 ---------
@@ -14,10 +16,16 @@ Signature
 Description
 -----------
 
-...
+**Low level directive** – unless you're sure you need to be working on this low-level you might instead
+want to try the :ref:`-handleRejections-` directive which provides a nicer DSL for building rejection handlers.
+
+See :ref:`-recoverRejections-` (the synchronous equivalent of this directive) for a detailed description.
+
+.. note::
+  To learn more about how and why rejections work read the :ref:`rejections-scala` section of the documentation.
 
 Example
 -------
 
 .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala
-   :snippet: 0recoverRejectionsWith
+   :snippet: recoverRejectionsWith