docs: normalize API reference version summaries

Author: huv1k

scripts/generate_openapi_reference.py

@@ -673,6 +673,35 @@ def add_operation_ids(spec: dict[str, Any]) -> None:
         print(f"==> Added {count} operationIds to envd endpoints")
 
 
+VERSIONED_PLATFORM_PATH_RE = re.compile(r"^/(v\d+)(?:/|$)", re.IGNORECASE)
+
+
+def normalize_versioned_summaries(spec: dict[str, Any]) -> int:
+    """Append `(vN)` to versioned platform endpoint summaries when missing."""
+    count = 0
+    for ep_path, path_item in spec.get("paths", {}).items():
+        match = VERSIONED_PLATFORM_PATH_RE.match(ep_path)
+        if not match:
+            continue
+
+        version_label = match.group(1).lower()
+        for method in ("get", "post", "put", "patch", "delete", "head", "options"):
+            op = path_item.get(method)
+            if not op:
+                continue
+
+            summary = op.get("summary")
+            if not isinstance(summary, str) or not summary.strip():
+                continue
+            if re.search(rf"\({re.escape(version_label)}\)", summary, re.IGNORECASE):
+                continue
+
+            op["summary"] = f"{summary.rstrip()} ({version_label})"
+            count += 1
+
+    return count
+
+
 STREAMING_ENDPOINTS = {
     "/filesystem.Filesystem/WatchDir",
     "/process.Process/Start",
@@ -1152,6 +1181,12 @@ def _singularize(word: str) -> str:
     if summary_count:
         fixes.append(f"Added summary to {summary_count} platform endpoints")
 
+    normalized_summary_count = normalize_versioned_summaries(spec)
+    if normalized_summary_count:
+        fixes.append(
+            f"Normalized version suffix on {normalized_summary_count} versioned endpoint summaries"
+        )
+
     # 27. Replace nullable: true with OpenAPI 3.1.0 type arrays
     #     In 3.1.0, nullable was removed. Use type: ["string", "null"] instead,
     #     or oneOf with type: 'null' for $ref properties.