Add meta-info and query strings to streaming doc

lib/pleroma/web/api_spec/operations/streaming_operation.ex

@@ -25,10 +25,25 @@ defmodule Pleroma.Web.ApiSpec.StreamingOperation do
     %Operation{
       tags: ["Timelines"],
       summary: "Establish streaming connection",
-      description: "Receive statuses in real-time via WebSocket.",
+      description: """
+      Receive statuses in real-time via WebSocket.
+
+      You can specify the access token on the query string or through the `sec-websocket-protocol` header. Using
+      the query string to authenticate is considered unsafe and should not be used unless you have to (e.g. to maintain
+      your client's compatibility with Mastodon).
+
+      You may specify a stream on the query string. If you do so and you are connecting to a stream that requires logged-in users,
+      you must specify the access token at the time of the connection (i.e. via query string or header).
+
+      Otherwise, you have the option to authenticate after you have established the connection through client-sent events.
+
+      The "Request body" section below describes what events clients can send through WebSocket, and the "Responses" section
+      describes what events server will send through WebSocket.
+      """,
       security: [%{"oAuth" => ["read:statuses", "read:notifications"]}],
       operationId: "WebsocketHandler.streaming",
-      parameters: [
+      parameters:
+        [
           Operation.parameter(:connection, :header, %Schema{type: :string}, "connection header",
             required: true
           ),
@@ -49,7 +64,7 @@ defmodule Pleroma.Web.ApiSpec.StreamingOperation do
             "sec-websocket-version header",
             required: true
           )
-      ],
+        ] ++ stream_params() ++ access_token_params(),
       requestBody: request_body("Client-sent events", client_sent_events()),
       responses: %{
         101 => switching_protocols_response(),
@@ -63,6 +78,20 @@ defmodule Pleroma.Web.ApiSpec.StreamingOperation do
     }
   end
 
+  defp stream_params do
+    stream_specifier()
+    |> Enum.map(fn {name, schema} ->
+      Operation.parameter(name, :query, schema, get_schema(schema).description)
+    end)
+  end
+
+  defp access_token_params do
+    [
+      Operation.parameter(:access_token, :query, token(), token().description),
+      Operation.parameter(:"sec-websocket-protocol", :header, token(), token().description)
+    ]
+  end
+
   defp switching_protocols_response do
     %Response{
       description: "Switching protocols",
@@ -379,14 +408,18 @@ defmodule Pleroma.Web.ApiSpec.StreamingOperation do
       "Authenticate via an access token.",
       "pleroma:authenticate",
       %{
-        token: %Schema{
+        token: token()
+      },
+      required: [:token]
+    )
+  end
+
+  defp token do
+    %Schema{
       type: :string,
       description: "An OAuth access token with corresponding permissions.",
       example: "some token"
     }
-      },
-      required: [:token]
-    )
   end
 
   defp stream_specifier do