Fix schema and consistency issues from second SDK testing round

Schema fixes:
- EntryInfo.type: add 'directory' to enum (was file-only)
- SandboxMetadata, EnvVars: add type: object (had only additionalProperties)
- TemplateLegacy: add missing 'names' and 'buildStatus' fields
- connect-protocol-version: remove redundant enum (const suffices)
- filesystem.EntryInfo.size: document int/string union type (int64)

Response fixes:
- PATCH /templates/{templateID}: return TemplateUpdateResponse (was empty)
- POST /sandboxes/{sandboxID}/refreshes: add missing 500 response
- GET /health 502: content-type → application/json (was connect+json)

Also fix fill_empty_responses to skip $ref responses.

Author: beran-t

openapi-public.yml

@@ -18,7 +18,7 @@ paths:
         '502': &id001
           description: Sandbox not found
           content:
-            application/connect+json:
+            application/json:
               schema:
                 type: object
                 required:
@@ -1261,6 +1261,8 @@ paths:
           $ref: '#/components/responses/401'
         '404':
           $ref: '#/components/responses/404'
+        '500':
+          $ref: '#/components/responses/500'
       operationId: postSandboxeRefreshes
     servers:
     - *id006
@@ -1575,11 +1577,10 @@ paths:
       responses:
         '200':
           description: The template was updated successfully
-          content: &id007
+          content:
             application/json:
               schema:
-                type: object
-                description: Empty response
+                $ref: '#/components/schemas/TemplateUpdateResponse'
         '400':
           $ref: '#/components/responses/400'
         '401':
@@ -1603,7 +1604,11 @@ paths:
       responses:
         '202':
           description: The build has started
-          content: *id007
+          content: &id007
+            application/json:
+              schema:
+                type: object
+                description: Empty response
         '401':
           $ref: '#/components/responses/401'
         '500':
@@ -2241,11 +2246,13 @@ components:
           description: Type of the file
           enum:
           - file
+          - directory
       type: object
     EnvVars:
       additionalProperties:
         type: string
         description: Environment variables for the sandbox
+      type: object
     Metrics:
       type: object
       description: Resource usage metrics
@@ -2282,8 +2289,6 @@ components:
     connect-protocol-version:
       type: number
       title: Connect-Protocol-Version
-      enum:
-      - 1
       description: Define the version of the Connect protocol
       const: 1
     connect-timeout-header:
@@ -2327,6 +2332,8 @@ components:
           - string
           title: size
           format: int64
+          description: File size in bytes. Encoded as string for values exceeding
+            JSON number precision (int64).
         mode:
           type: integer
           title: mode
@@ -3039,6 +3046,7 @@ components:
       additionalProperties:
         type: string
         description: Metadata of the sandbox
+      type: object
     SandboxState:
       type: string
       description: State of the sandbox
@@ -3655,6 +3663,13 @@ components:
           description: Number of times the template was built
         envdVersion:
           $ref: '#/components/schemas/EnvdVersion'
+        names:
+          type: array
+          description: Names of the template (namespace/alias format when namespaced)
+          items:
+            type: string
+        buildStatus:
+          $ref: '#/components/schemas/TemplateBuildStatus'
       type: object
     TemplateBuild:
       required:

scripts/generate_openapi_reference.py

@@ -892,6 +892,86 @@ def fix_spec_issues(spec: dict[str, Any]) -> None:
                     param["description"] = schema.pop("description")
                     fixes.append(f"{ep_path}: moved 'end' description out of schema")
 
+    # 18. EntryInfo.type enum incomplete — missing "directory"
+    entry_info = schemas.get("EntryInfo")
+    if entry_info:
+        type_prop = entry_info.get("properties", {}).get("type")
+        if type_prop and type_prop.get("enum") == ["file"]:
+            type_prop["enum"] = ["file", "directory"]
+            fixes.append("EntryInfo.type: added 'directory' to enum")
+
+    # 19. SandboxMetadata and EnvVars lack type: object
+    for name in ("SandboxMetadata", "EnvVars"):
+        schema = schemas.get(name, {})
+        if "additionalProperties" in schema and "type" not in schema:
+            schema["type"] = "object"
+            fixes.append(f"{name}: added type: object")
+
+    # 20. TemplateLegacy missing 'names' and 'buildStatus' fields
+    tpl_legacy = schemas.get("TemplateLegacy")
+    if tpl_legacy and "properties" in tpl_legacy:
+        props = tpl_legacy["properties"]
+        if "names" not in props:
+            props["names"] = {
+                "type": "array",
+                "description": "Names of the template (namespace/alias format when namespaced)",
+                "items": {"type": "string"},
+            }
+            fixes.append("TemplateLegacy: added 'names' property")
+        if "buildStatus" not in props:
+            props["buildStatus"] = {"$ref": "#/components/schemas/TemplateBuildStatus"}
+            fixes.append("TemplateLegacy: added 'buildStatus' property")
+
+    # 21. connect-protocol-version: redundant enum + const
+    cpv = schemas.get("connect-protocol-version")
+    if cpv and "enum" in cpv and "const" in cpv:
+        del cpv["enum"]
+        fixes.append("connect-protocol-version: removed redundant enum (const is sufficient)")
+
+    # 22. filesystem.EntryInfo.size union type undocumented
+    fs_entry = schemas.get("filesystem.EntryInfo")
+    if fs_entry and "properties" in fs_entry:
+        size_prop = fs_entry["properties"].get("size")
+        if size_prop and isinstance(size_prop.get("type"), list):
+            size_prop["description"] = (
+                "File size in bytes. Encoded as string for values exceeding "
+                "JSON number precision (int64)."
+            )
+            fixes.append("filesystem.EntryInfo.size: documented integer/string union type")
+
+    # 23. GET /health 502 uses application/connect+json — change to application/json
+    if health_get:
+        for status_code, resp in health_get.get("responses", {}).items():
+            if not isinstance(resp, dict):
+                continue
+            content = resp.get("content", {})
+            if "application/connect+json" in content and "application/json" not in content:
+                content["application/json"] = content.pop("application/connect+json")
+                fixes.append(f"/health {status_code}: content-type → application/json")
+
+    # 24. PATCH /templates/{templateID} (deprecated) returns empty object —
+    #     use TemplateUpdateResponse like v2
+    patch_v1_path = paths.get("/templates/{templateID}", {})
+    patch_v1 = patch_v1_path.get("patch")
+    if patch_v1:
+        resp_200 = patch_v1.get("responses", {}).get("200", {})
+        # Replace the entire content dict (don't modify shared YAML anchor object)
+        resp_200["content"] = {
+            "application/json": {
+                "schema": {"$ref": "#/components/schemas/TemplateUpdateResponse"}
+            }
+        }
+        fixes.append("PATCH /templates/{templateID}: response → TemplateUpdateResponse")
+
+    # 25. POST /sandboxes/{sandboxID}/refreshes missing 500 response
+    refreshes_path = paths.get("/sandboxes/{sandboxID}/refreshes", {})
+    refreshes_post = refreshes_path.get("post")
+    if refreshes_post:
+        responses = refreshes_post.get("responses", {})
+        if "500" not in responses:
+            responses["500"] = {"$ref": "#/components/responses/500"}
+            fixes.append("/sandboxes/{sandboxID}/refreshes: added 500 response")
+
     if fixes:
         print(f"==> Fixed {len(fixes)} spec issues:")
         for f in fixes: