openapi: Add intentionally_undocumentated parameter to REQ.

This will allow us to mark a REQ variable as intentionally
undocumented. With this, we can remove some of the endpoints marked
as "buggy" even though they're not actually buggy, we just needed to
specify certain parameters as intentionally undocumented (e.g. the
stream_id for the /users/me/subscriptions/muted_topics endpoint.)

Any REQ variable with intentionally_undocumentated set to True
will not be added to the arguments_map data structure.

For some of the other "buggy" endpoints, we would want to mark the
entire endpoint as being undocumented intentionally via. the urls.py
file.

zerver/lib/request.py

@@ -67,6 +67,7 @@ class REQ:
                  default: Any=NotSpecified, validator: Callable[[Any], Any]=None,
                  str_validator: Callable[[Any], Any]=None,
                  argument_type: str=None, type: Type=None,
+                 intentionally_undocumented=False,
                  aliases: Optional[List[str]]=None) -> None:
         """whence: the name of the request variable that should be used
         for this parameter.  Defaults to a request variable of the
@@ -103,6 +104,7 @@ class REQ:
         self.default = default
         self.argument_type = argument_type
         self.aliases = aliases
+        self.intentionally_undocumented = intentionally_undocumented
 
         if converter and (validator or str_validator):
             # Not user-facing, so shouldn't be tagged for translation
@@ -150,7 +152,11 @@ def has_request_variables(view_func: ViewFuncT) -> ViewFuncT:
             if value.post_var_name is None:
                 value.post_var_name = name
             post_params.append(value)
-            arguments_map[view_func_full_name].append(value.post_var_name)
+
+            # Record arguments that should be documented so that our
+            # automated OpenAPI docs tests can compare these against the code.
+            if not value.intentionally_undocumented:
+                arguments_map[view_func_full_name].append(value.post_var_name)
 
     @wraps(view_func)
     def _wrapped_view_func(request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:

zerver/lib/request.pyi

@@ -27,6 +27,7 @@ def REQ(whence: Optional[str] = None,
         validator: Optional[Validator] = None,
         str_validator: Optional[Validator] = None,
         argument_type: Optional[str] = None,
+        intentionally_undocumented: bool=False,
         aliases: Optional[List[str]] = None) -> ResultT: ...
 
 def has_request_variables(view_func: ViewFuncT) -> ViewFuncT: ...

zerver/tests/test_openapi.py

@@ -215,11 +215,7 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         BUGGY_DOCUMENTATION_ENDPOINTS = set([
             '/events',
             '/register',
-            '/mark_stream_as_read',
-            '/mark_topic_as_read',
             '/messages',
-            '/messages/flags',
-            '/messages/render',
             '/typing',
             '/users/me/subscriptions/muted_topics',
         ])

zproject/urls.py

@@ -34,6 +34,7 @@ import zerver.views.muting
 import zerver.views.streams
 import zerver.views.realm
 import zerver.views.digest
+import zerver.views.messages
 from zerver.context_processors import latest_info_context
 import zerver.views.public_export