apidocs: Add support for using OpenAPI title for /api pages.

The current logic of geneerating HTML titles requires the title to be
present as a heading in the first line of .md file. However, this will
shortly be no longer true for /api pages where these are
auto-generated from OpenAPI data.  Modified the code to fetch the
title from OpenAPI data in case of such pages.

zerver/openapi/openapi.py

@@ -7,7 +7,7 @@
 
 import os
 import re
-from typing import Any, Dict, List, Optional, Set
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 from jsonschema.exceptions import ValidationError as JsonSchemaValidationError
 from openapi_core import create_spec
@@ -218,6 +218,15 @@ def get_openapi_summary(endpoint: str, method: str) -> str:
     return openapi_spec.openapi()["paths"][endpoint][method.lower()]["summary"]
 
 
+def get_endpoint_from_operationid(operationid: str) -> Tuple[str, str]:
+    for endpoint in openapi_spec.openapi()["paths"]:
+        for method in openapi_spec.openapi()["paths"][endpoint]:
+            operationId = openapi_spec.openapi()["paths"][endpoint][method].get("operationId")
+            if operationId == operationid:
+                return (endpoint, method)
+    raise AssertionError("No such page exists in OpenAPI data.")
+
+
 def get_openapi_paths() -> Set[str]:
     return set(openapi_spec.openapi()["paths"].keys())
 

zerver/views/documentation.py

@@ -15,6 +15,7 @@ from zerver.lib.integrations import CATEGORIES, INTEGRATIONS, HubotIntegration,
 from zerver.lib.request import REQ, has_request_variables
 from zerver.lib.subdomains import get_subdomain
 from zerver.models import Realm
+from zerver.openapi.openapi import get_endpoint_from_operationid, get_openapi_summary
 from zerver.templatetags.app_filters import render_markdown_path
 
 
@@ -105,7 +106,12 @@ class MarkdownDirectoryView(ApiURLView):
             with open(article_path) as article_file:
                 first_line = article_file.readlines()[0]
             # Strip the header and then use the first line to get the article title
-            article_title = first_line.lstrip("#").strip()
+            if self.path_template == "/zerver/api/%s.md" and first_line[0] != "#":
+                api_operation = context["OPEN_GRAPH_URL"].split("/api/")[1].replace("-", "_")
+                endpoint_path, endpoint_method = get_endpoint_from_operationid(api_operation)
+                article_title = get_openapi_summary(endpoint_path, endpoint_method)
+            else:
+                article_title = first_line.lstrip("#").strip()
             if context["not_index_page"]:
                 context["OPEN_GRAPH_TITLE"] = f"{article_title} ({title_base})"
             else: