openapi_docs: Display deprecated parameters with a deprecated tag.

In zulip.yaml, add `deprecated` tags to all parameters/keys with
`Deprecated` in the description. Then add tests to ensure that deprecated
parameters/keys will always have the `deprecated` key. Also, in
the API docs, sort the parameters according to presence of `deprecated`
key, presenting the `deprecated` keys at the end and add a `deprecated`
tag next to them.

static/styles/portico/portico.scss

@@ -1730,6 +1730,13 @@ input.new-organization-button {
         font-size: 12px;
         color: hsl(0, 0%, 47%);
     }
+
+    .api-argument-deprecated {
+        text-transform: uppercase;
+        font-weight: 600;
+        font-size: 12px;
+        color: hsl(0, 50%, 60%);
+    }
 }
 
 .desktop-redirect-box {

zerver/lib/bugdown/api_arguments_table_generator.py

@@ -8,7 +8,7 @@ from django.utils.html import escape as escape_html
 from markdown.extensions import Extension
 from markdown.preprocessors import Preprocessor
 
-from zerver.openapi.openapi import get_openapi_parameters
+from zerver.openapi.openapi import get_openapi_parameters, likely_deprecated_parameter
 
 REGEXP = re.compile(r'\{generate_api_arguments_table\|\s*(.+?)\s*\|\s*(.+)\s*\}')
 
@@ -92,7 +92,7 @@ class APIArgumentsTablePreprocessor(Preprocessor):
         table = []
         argument_template = """
 <div class="api-argument">
-    <p class="api-argument-name"><strong>{argument}</strong> {required}</p>
+    <p class="api-argument-name"><strong>{argument}</strong> {required} {deprecated}</p>
     <div class="api-example">
         <span class="api-argument-example-label">Example</span>: <code>{example}</code>
     </div>
@@ -101,7 +101,7 @@ class APIArgumentsTablePreprocessor(Preprocessor):
 </div>"""
 
         md_engine = markdown.Markdown(extensions=[])
-
+        arguments = sorted(arguments, key=lambda argument: 'deprecated' in argument)
         for argument in arguments:
             description = argument['description']
             oneof = ['`' + str(item) + '`'
@@ -132,10 +132,19 @@ class APIArgumentsTablePreprocessor(Preprocessor):
             else:
                 required_block = '<span class="api-argument-optional">optional</span>'
 
+            # Test to make sure deprecated parameters are marked so.
+            if likely_deprecated_parameter(description):
+                assert(argument['deprecated'])
+            if argument.get('deprecated', False):
+                deprecated_block = '<span class="api-argument-deprecated">Deprecated</span>'
+            else:
+                deprecated_block = ''
+
             table.append(argument_template.format(
                 argument=argument.get('argument') or argument.get('name'),
                 example=escape_html(example),
                 required=required_block,
+                deprecated=deprecated_block,
                 description=md_engine.convert(description),
             ))
 

zerver/lib/bugdown/api_return_values_table_generator.py

@@ -5,7 +5,7 @@ import markdown
 from markdown.extensions import Extension
 from markdown.preprocessors import Preprocessor
 
-from zerver.openapi.openapi import get_openapi_return_values
+from zerver.openapi.openapi import get_openapi_return_values, likely_deprecated_parameter
 
 REGEXP = re.compile(r'\{generate_return_values_table\|\s*(.+?)\s*\|\s*(.+)\s*\}')
 
@@ -62,6 +62,9 @@ class APIReturnValuesTablePreprocessor(Preprocessor):
             if return_value in IGNORE:
                 continue
             description = return_values[return_value]['description']
+            # Test to make sure deprecated keys are marked appropriately.
+            if likely_deprecated_parameter(description):
+                assert(return_values[return_value]['deprecated'])
             ans.append(self.render_desc(description, spacing, return_value))
             if 'properties' in return_values[return_value]:
                 ans += self.render_table(return_values[return_value]['properties'], spacing + 4)

zerver/openapi/openapi.py

@@ -340,3 +340,9 @@ def to_python_type(py_type: str) -> type:
     }
 
     return TYPES[py_type]
+
+def likely_deprecated_parameter(parameter_description: str) -> bool:
+    if '**Changes**: Deprecated' in parameter_description:
+        return True
+
+    return "**Deprecated**" in parameter_description

zerver/openapi/zulip.yaml

@@ -550,6 +550,7 @@ paths:
         example: false
       - name: use_first_unread_anchor
         in: query
+        deprecated: true
         description: |
           Legacy way to specify `anchor="first_unread"` in Zulip 2.1.x and older.
 
@@ -1959,6 +1960,7 @@ paths:
                       example: "2019-10-20T07:50:53.728864+00:00"
                     max_message_id:
                       type: integer
+                      deprecated: true
                       description: |
                         The integer ID of the last message received by your account.
 
@@ -2272,12 +2274,14 @@ paths:
                               opposite value, `in_home_view=!is_muted`).
                           in_home_view:
                             type: boolean
+                            deprecated: true
                             description: |
                               Legacy property for if the given stream is muted, with inverted meeting.
 
                               **Deprecated**; clients should use is_muted where available.
                           is_announcement_only:
                             type: boolean
+                            deprecated: true
                             description: |
                               Whether only organization administrators can post to the stream.
 
@@ -3275,6 +3279,7 @@ paths:
                 - properties:
                     authentication_methods:
                       type: object
+                      deprecated: true
                       description: |
                         Each key-value pair in the object indicates whether the authentication
                         method is enabled on this server.
@@ -3840,6 +3845,7 @@ paths:
                               Null is used for streams with no message history.
                           is_announcement_only:
                             type: boolean
+                            deprecated: true
                             description: |
                               Whether the given stream is announcement only or not.
 
@@ -3992,6 +3998,7 @@ paths:
         required: false
       - name: is_announcement_only
         in: query
+        deprecated: true
         description: |
           Whether the stream is limited to announcements.
 
@@ -4546,6 +4553,7 @@ components:
                   object is deprecated and will be removed in the future.
               user:
                 type: object
+                deprecated: true
                 description: |
                   Dictionary with data on the user who added the reaction, including
                   the user ID as the `id` field.  **Note**: In the [events