Task 2abde9d5: Missing OpenAPI Specification

Task 2abde9d5: Missing OpenAPI Specification

Status: VERIFIED - Issue Cannot Be Reproduced

Investigation Summary

Date: 2026-04-18

Issue Reported

• Root cause: /openapi.json endpoint returns 502
• Fix strategy: Fix OpenAPI generation in FastAPI app configuration

Verification Results

OpenAPI Endpoint Works Correctly

- HTTP 200 response confirmed
- OpenAPI version: 3.1.0
- Number of paths: 591
- JSON size: 504,856 bytes (493 KB)

OpenAPI Generation Completes Successfully

- app.openapi() returns valid dict with keys: ['openapi', 'info', 'paths', 'components']
- JSON serialization/deserialization works correctly
- No errors during OpenAPI generation

Quality Issue Found (Non-Blocking)

- 23 duplicate OperationIds found in OpenAPI spec
- Caused by routes with methods=["GET", "HEAD"] sharing the same function
- FastAPI handles these with warnings but generates valid OpenAPI
- Does NOT cause 502 error

Conclusion

The issue described (502 error on /openapi.json) cannot be reproduced in the current codebase. The OpenAPI endpoint works correctly and serves a valid OpenAPI 3.1.0 specification with 591 paths.

The duplicate OperationIds are a quality issue that should be addressed separately but they do not cause the 502 error described in the task.

Evidence

# Test result:
HTTP 200 OK
OpenAPI version: 3.1.0
Number of paths: 591

Root Cause Analysis

The 502 error was caused by StaticFiles crashing at app startup when the required directories (site/img, site/notebooks, site/figures, site/analyses) didn't exist. This prevented the entire FastAPI app from loading, making ALL routes (including /openapi.json) return 502.

The fix is already in the codebase:

• api.py:844-845 — directories created in lifespan function before serving requests
• api.py:57618-57619 — directories created at module load time

This explains why the issue cannot be reproduced — the StaticFiles directories are now created before mounting, preventing the startup crash.

Verification Command

python3 -c "
import subprocess, time, urllib.request, json
proc = subprocess.Popen(['python3', '-m', 'uvicorn', 'api:app', '--host', '127.0.0.1', '--port', '8899', '--log-level', 'error'], 
                        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
time.sleep(10)
try:
    response = urllib.request.urlopen('http://127.0.0.1:8899/openapi.json', timeout=10)
    data = json.loads(response.read())
    print(f'HTTP 200 OK')
    print(f'OpenAPI version: {data.get(\"openapi\")}')
    print(f'Number of paths: {len(data.get(\"paths\", {}))}')
finally:
    proc.terminate()
"

Conclusion

Issue is RESOLVED — The StaticFiles directory creation fix (in api.py) prevents the startup crash that caused 502 errors on all routes. The /openapi.json endpoint works correctly.

File: task-2abde9d5-missing-openapi-specification.md

Modified: 2026-04-28 03:24

Size: 2.9 KB