chore: update documentation for telephony

scripts/dump_docs_openapi.py

@@ -0,0 +1,39 @@
+"""Dump the FastAPI OpenAPI spec to docs/api-reference/openapi.json.
+
+Run from the repo root with the api environment available:
+
+    python -m scripts.dump_docs_openapi
+
+CI uses this to detect drift: it dumps the spec and asserts the file is
+unchanged versus what's checked in.
+"""
+
+import json
+from pathlib import Path
+
+from loguru import logger
+
+logger.remove()
+
+from fastapi.openapi.utils import get_openapi  # noqa: E402
+
+from api.app import app  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+OUTPUT = REPO_ROOT / "docs" / "api-reference" / "openapi.json"
+
+
+def main() -> None:
+    spec = get_openapi(
+        title=app.title,
+        version=app.version,
+        description=app.description,
+        routes=app.routes,
+        servers=app.servers,
+    )
+    OUTPUT.write_text(json.dumps(spec, separators=(",", ":")))
+    print(f"Wrote {len(spec['paths'])} paths to {OUTPUT.relative_to(REPO_ROOT)}")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_sdk.sh

@@ -6,6 +6,8 @@
 #   3. Pydantic request/response models + TS interfaces (datamodel-codegen
 #      / openapi-typescript)
 #   4. Client method mixins (_generated_client.py / _generated_client.ts)
+#   5. Full OpenAPI spec for the Mintlify docs site
+#      (docs/api-reference/openapi.json)
 #
 # Run from anywhere — the script resolves the repo root relative to itself.
 # Requires:
@@ -106,4 +108,9 @@ python -m sdk.codegen.client_codegen \
     --py-out "sdk/python/src/dograh_sdk/_generated_client.py" \
     --ts-out "sdk/typescript/src/_generated_client.ts"
 
+# ── 5. Docs OpenAPI spec ─────────────────────────────────────────────
+
+echo "→ Dumping full OpenAPI spec for docs site..."
+python -m scripts.dump_docs_openapi
+
 echo "✓ SDK regenerated."