Merge pull request #18847 from ktoso/wip-migration-rawquery-ktoso

=doc #18715 migration guide for Query in Akka HTTP

akka-docs-dev/rst/scala/code/docs/MigrationsScala.scala

@@ -1,5 +1,6 @@
 package docs
 
+import akka.http.scaladsl.model.Uri
 import akka.stream.scaladsl._
 import akka.stream._
 import akka.stream.stage.{ OutHandler, InHandler, GraphStageLogic, GraphStage }
@@ -198,6 +199,15 @@ class MigrationsScala extends AkkaSpec {
         }
 
         //#port-async
+
+        val uri: Uri = ???
+        //#raw-query
+        val queryPart: Option[String] = uri.rawQueryString
+        //#raw-query
+
+        //#query-param
+        val param: Option[String] = uri.query().get("a")
+        //#query-param
       }
     }
   }

akka-docs-dev/rst/scala/migration-guide-1.0-2.x-scala.rst

@@ -409,3 +409,44 @@ Example
 should be replaced by
 
 .. includecode:: code/docs/MigrationsScala.scala#port-async
+
+Akka HTTP: Uri parsing mode relaxed-with-raw-query replaced with rawQueryString
+===============================================================================
+
+Previously Akka HTTP allowed to configure the parsing mode of an Uri's Query part (``?a=b&c=d``) to ``relaxed-with-raw-query``
+which is useful when Uris are not formatted using the usual "key/value pairs" syntax.
+
+Instead of exposing it as an option for the parser, this is now available as the ``rawQueryString(): Option[String]``
+/ ``queryString(): Option[String]`` methods on on ``model.Uri``.
+
+
+For parsing the Query part use ``query(charset: Charset = UTF8, mode: Uri.ParsingMode = Uri.ParsingMode.Relaxed): Query``.
+
+Update procedure
+----------------
+1. If the ``uri-parsing-mode`` was set to ``relaxed-with-raw-query``, remove it
+2. In places where the query string was accessed in ``relaxed-with-raw-query`` mode, use the ``rawQueryString``/``queryString`` methods instead
+3. In places where the parsed query parts (such as ``parameter``) were used, invoke parsing directly using ``uri.query().get("a")``
+
+Example
+^^^^^^^
+
+::
+
+  // config, no longer works
+  akka.http.parsing.uri-parsing-mode = relaxed-with-raw-query
+
+should be replaced by:
+
+.. includecode:: code/docs/Migrations.scala#raw-query
+
+And use of query parameters from ``Uri`` that looked like this:
+
+::
+
+  // This no longer works!
+  uri.parameter("name")
+
+should be replaced by:
+
+.. includecode:: code/docs/Migrations.scala#query-param