Regenerate API spec during docs build (#551)

Author: shayancoin

backend/api/exports.py

@@ -24,7 +24,7 @@
 from api.security import require_write_token
 from api.storage_dependencies import get_storage_client
 from backend.services.storage import StorageClient, StoredObject
-from services.cnc_service import CNCService
+from backend.services.cnc_service import CNCService
 
 logger = logging.getLogger(__name__)
 router = APIRouter(

backend/api/routes_orders.py

@@ -10,7 +10,7 @@
 
 from api import models
 from api.db import get_db
-from api.schemas import Order, OrderCreate, OrderUpdate
+from api.schemas import Order, OrderCreate, OrderResponse, OrderUpdate
 from schemas.pricing import QuoteTotals
 
 router = APIRouter(prefix="/api/orders", tags=["orders"])

backend/api/schemas.py

@@ -183,6 +183,23 @@ class OrderCheckoutPreferences(BaseModel):
     cancel_url: AnyUrl | None = None
 
 
+class OrderPayment(BaseModel):
+    provider: str | None = Field(default=None, max_length=50)
+    reference: str | None = Field(default=None, max_length=128)
+    status: str | None = Field(default=None, max_length=50)
+    amount: float | None = None
+    currency: str | None = Field(default=None, max_length=3)
+    processed_at: datetime | None = None
+    metadata: dict[str, Any] | None = Field(default=None, alias="metadata_", serialization_alias="metadata")
+
+
+class OrderDesign(BaseModel):
+    step_url: AnyUrl | None = Field(default=None, alias="step_url")
+    ifc_url: AnyUrl | None = Field(default=None, alias="ifc_url")
+    preview_url: AnyUrl | None = Field(default=None, alias="preview_url")
+    metadata: dict[str, Any] | None = Field(default=None, alias="metadata_", serialization_alias="metadata")
+
+
 class OrderBase(BaseModel):
     quote_id: str
     channel: OrderChannel = Field(default=OrderChannel.SHOPIFY)
@@ -249,12 +266,12 @@ class Order(OrderBase):
     status: str | None = None
     checkout_url: str | None = None
     shopify_order_id: str | None = None
-    totals: OrderTotals
+    totals: QuoteTotals
     created_at: datetime
     updated_at: datetime
 
 
-class OrderResponse(OrderSummary):
+class OrderResponse(Order):
     customer: OrderCustomer | None = None
     shipping_address: OrderAddress | None = None
     billing_address: OrderAddress | None = None
@@ -267,5 +284,13 @@ class OrderResponse(OrderSummary):
 
 
 class OrderListResponse(BaseModel):
-    items: List[OrderSummary]
+    items: List[Order]
     next_cursor: str | None = None
+
+
+# Ensure forward references between order schemas are resolved for OpenAPI generation
+Order.model_rebuild()
+OrderCreate.model_rebuild()
+OrderUpdate.model_rebuild()
+OrderResponse.model_rebuild()
+OrderListResponse.model_rebuild()

backend/models/order.py

@@ -5,7 +5,7 @@
 import uuid
 from datetime import datetime
 from enum import Enum
-from typing import Any
+from typing import Any, TYPE_CHECKING
 
 from sqlalchemy import (
     Enum as SqlEnum,

backend/scripts/generate_openapi.py

@@ -1,9 +1,23 @@
 #!/usr/bin/env python3
 from __future__ import annotations
+
 import json
+from pathlib import Path
+import sys
+
+# Ensure the project root is on the Python path when executing directly
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+BACKEND_ROOT = PROJECT_ROOT / "backend"
+
+for path in (PROJECT_ROOT, BACKEND_ROOT):
+    path_str = str(path)
+    if path_str in sys.path:
+        sys.path.remove(path_str)
+    sys.path.insert(0, path_str)
+
 from api.main import app
 
 if __name__ == "__main__":
     # Use FastAPI's baked schema to include all route/reg metadata
     spec = app.openapi()
-    print(json.dumps(spec, indent=2))
+    print(json.dumps(spec, indent=2))

build-docs.sh

@@ -8,32 +8,59 @@ npm install
 npm run build
 cd ..
 
-# Create template-ui directory in docs/assets
-echo "Setting up template UI in docs..."
-mkdir -p docs/assets/template-ui
-cp -r frontend/out/* docs/assets/template-ui/
+# Create template-ui directory in docs/assets if static export exists
+if [ -d frontend/out ]; then
+  echo "Setting up template UI in docs..."
+  mkdir -p docs/assets/template-ui
+  cp -r frontend/out/* docs/assets/template-ui/
 
-# Ensure images are available in multiple locations
-mkdir -p docs/assets/template-ui/images
-cp -r frontend/public/images/* docs/assets/template-ui/images/
+  # Ensure images are available in multiple locations
+  mkdir -p docs/assets/template-ui/images
+  cp -r frontend/public/images/* docs/assets/template-ui/images/
 
-# Also copy images to root of template-ui
-cp -r frontend/public/images/* docs/assets/template-ui/
+  # Also copy images to root of template-ui
+  cp -r frontend/public/images/* docs/assets/template-ui/
 
-# And to assets directory
-mkdir -p docs/assets/images
-cp -r frontend/public/images/* docs/assets/images/
+  # And to assets directory
+  mkdir -p docs/assets/images
+  cp -r frontend/public/images/* docs/assets/images/
+else
+  echo "Warning: frontend/out not found; skipping template UI asset copy." >&2
+fi
 
 # Build MkDocs site (which will include the template UI)
 echo "Building MkDocs site..."
+
+# Ensure the backend virtualenv is activated before generating the OpenAPI spec
+if [ -d "backend/.venv" ]; then
+  # shellcheck disable=SC1091
+  source backend/.venv/bin/activate
+else
+  echo "Error: backend virtualenv not found at backend/.venv" >&2
+  exit 1
+fi
+
+export HYGRAPH_WEBHOOK_SECRET="${HYGRAPH_WEBHOOK_SECRET:-dummy-hygraph-secret}"
+export SHOPIFY_STORE="${SHOPIFY_STORE:-dummy-store}"
+export SHOPIFY_TOKEN="${SHOPIFY_TOKEN:-dummy-shopify-token}"
+export SHOPIFY_WEBHOOK_SECRET="${SHOPIFY_WEBHOOK_SECRET:-dummy-shopify-webhook}"
+export PYTHONPATH="${PWD}${PYTHONPATH:+:$PYTHONPATH}"
+
+python backend/scripts/generate_openapi.py > docs/API_SPEC.md
+
+# Deactivate the virtualenv to avoid affecting subsequent commands
+deactivate
+
 mkdocs build
 
 # Copy images to multiple locations in the site directory
 mkdir -p site/assets/template-ui/images
 cp -r frontend/public/images/* site/assets/template-ui/images/
 
-# Copy to root of template-ui
-cp -r frontend/public/images/* site/assets/template-ui/
+# Copy to root of template-ui if available
+if [ -d frontend/out ]; then
+  cp -r frontend/public/images/* site/assets/template-ui/
+fi
 
 # Copy to site/assets/images
 mkdir -p site/assets/images