api docs: Migrate REAL-TIME /events to OpenAPI.

Migrate "call_on_each_event" from api/arguments.json to
/events:real-time in OpenAPI.

This is a bit of a hack, but it lets us eliminate this secondary
arguments.json file, which is probably worth it.

Tweaked by tabbott to fix various formatting issues in the original
documentation while I was looking at it.

templates/zerver/api/arguments.json

@@ -1,16 +0,0 @@
-{
-    "call_on_each_event": [
-        {
-            "argument": "narrow",
-            "description": "A JSON-encoded array of length 2 indicating the narrow for which you'd like to receive events for. For instance, to receive events for the stream `Denmark`, you would specify `narrow=['stream', 'Denmark']`. Another example is `narrow=['is', 'private']` for private messages. Default is `[]`.",
-            "required": false,
-            "example": "narrow=['stream', 'Denmark']"
-        },
-        {
-            "argument": "event_types",
-            "description": "A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: <br/> <br/> * **message** (messages), <br/> * **subscription** (changes in your subscriptions), <br/> * **realm_user** (changes in the list of users in your realm)<br/> <br/> If you do not specify this argument, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: `event_types=['message']`",
-            "required": false,
-            "example": "event_types=['message']"
-        }
-    ]
-}

templates/zerver/api/real-time-events.md

@@ -54,4 +54,7 @@ client.call_on_each_event(lambda event: sys.stdout.write(str(event) + "\n"))
 
 You may also pass in the following keyword arguments to `call_on_each_event`:
 
-{generate_api_arguments_table|arguments.json|call_on_each_event}
+{generate_api_arguments_table|zulip.yaml|/real-time:post}
+
+See the [GET /events](/api/get-events-from-queue) documentation for
+more details on the format of individual events.

zerver/openapi/zulip.yaml

@@ -3254,6 +3254,53 @@ paths:
                             }
                         ]
                     }
+  /real-time:
+    # This entry is a hack; it exists to give us a place to put the text
+    # documenting the arguments for call_on_each_event and friends.
+    post:
+      description: (Ignored)
+      parameters:
+      - name: narrow
+        in: query
+        description: |
+          A JSON-encoded array of length 2 indicating the narrow
+          for which you'd like to receive events for. For instance, to receive
+          events for the stream `Denmark`, you would specify
+          `narrow=['stream', 'Denmark']`. Another example is
+          `narrow=['is', 'private']` for private messages. Default is `[]`.
+        schema:
+          type: array
+          items:
+            type: string
+        example: narrow=['stream', 'Denmark']
+        required: false
+      - name: event_types
+        in: query
+        description: |
+          A JSON-encoded array indicating which types of events you're
+          interested in. Values that you might find useful include:
+
+            * **message** (messages)
+            * **subscription** (changes in your subscriptions)
+            * **realm_user** (changes to users in the organization and
+              their properties, such as their name).
+
+          If you do not specify this argument, you will receive all
+          events, and have to filter out the events not relevant to
+          your client in your client code.  For most applications, one
+          is only interested in messages, so one specifies:
+          `event_types=['message']`
+        schema:
+          type: array
+          items:
+            type: string
+          default:
+        example: event_types=['message']
+        required: false
+        default: null
+      security:
+      - basicAuth: []
+
 components:
   #######################
   # Security definitions

zerver/tests/test_openapi.py

@@ -200,6 +200,9 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         # section of the same page.
         '/users/me/subscriptions/{stream_id}',
 
+        # Real-time-events endpoint
+        '/real-time',
+
         #### Mobile-app only endpoints; important for mobile developers.
         # Mobile interface for fetching API keys
         '/fetch_api_key',