api: Document new get_messages oldest/newest API feature.

While we're at it, we make the examples more sensible.

templates/zerver/api/get-messages.md

@@ -63,7 +63,7 @@ zulip(config).then((client) => {
 
 {tab|curl}
 
-{generate_code_example(curl, exclude=["client_gravatar", "apply_markdown"])|/messages:get|example}
+{generate_code_example(curl, exclude=["client_gravatar", "apply_markdown", "use_first_unread_anchor"])|/messages:get|example}
 
 {end_tabs}
 

tools/linter_lib/custom_check.py

@@ -799,6 +799,7 @@ markdown_docs_length_exclude = {
     "templates/zerver/integrations/perforce.md",
     # Has some example code that could perhaps be wrapped
     "templates/zerver/api/incoming-webhooks-walkthrough.md",
+    "templates/zerver/api/get-messages.md",
     # This macro has a long indented URL
     "templates/zerver/help/include/git-webhook-url-with-branches-indented.md",
     "templates/zerver/api/update-notification-settings.md",

zerver/openapi/python_examples.py

@@ -543,15 +543,13 @@ def get_messages(client):
     # type: (Client) -> None
 
     # {code_example|start}
-    # Get the 3 last messages sent by "iago@zulip.com" to the stream "Verona"
+    # Get the 100 last messages sent by "iago@zulip.com" to the stream "Verona"
     request = {
-        'use_first_unread_anchor': True,
-        'num_before': 3,
+        'anchor': 'newest',
+        'num_before': 100,
         'num_after': 0,
         'narrow': [{'operator': 'sender', 'operand': 'iago@zulip.com'},
                    {'operator': 'stream', 'operand': 'Verona'}],
-        'client_gravatar': True,
-        'apply_markdown': True
     }  # type: Dict[str, Any]
     result = client.get_messages(request)
     # {code_example|end}

zerver/openapi/zulip.yaml

@@ -290,6 +290,9 @@ paths:
         in: query
         description: The message ID to fetch messages near.
           Required unless `use_first_unread_anchor` is set to true.
+
+          The special values of `'newest'` and `'oldest'` are also supported
+          for anchoring the query at the most recent or oldest messages.
         schema:
           oneOf:
             - type: string