Skip to main content

​
Objective

This workflow ensures that docs.json remains perfectly synchronized with the public Rhombus OpenAPI specification at: https://api2.rhombussystems.com/api/openapi/public.json. It validates and updates documentation only using the official OpenAPI data—no speculative or hallucinated content. The process operates in controlled batches for large files, ensuring performance, consistency, and auditability.

​
Key Guardrails

  • Single Source of Truth: The OpenAPI spec defines all endpoint and field content. Missing fields remain blank or receive a TODO placeholder—never invented.
  • Deterministic Merging: Custom fields in docs.json (e.g., internal notes or examples) are preserved. Only OpenAPI-derived data is updated.
  • Schema Integrity: The resulting JSON structure undergoes validation before commit.
  • Idempotency: Running the workflow multiple times without spec changes produces identical output.
  • Scalable for Large Specs: Processes endpoints in configurable batches with progress indicators.

​
Directory Structure and File Conventions

  • Cached OpenAPI file: .cache/openapi-public.json
  • Update tool (auto-created if missing): tools/update_docs_from_openapi.py
  • Input file: docs/docs.json (existing structure preserved)
  • Temporary output: docs/docs.next.json
  • Change log: docs/api_sync_changelog.md

​
Workflow Summary

  1. Download and Cache the latest OpenAPI spec using conditional GET requests.
  2. Validate JSON structure and calculate the content hash.
  3. Normalize and Format parameters, request bodies, and responses—improving readability without altering meaning.
  4. Merge Changes into docs.json:
    • Add new endpoints.
    • Update existing endpoints.
    • Retain any non-spec custom fields.
    • Mark removed endpoints as deprecated: true with timestamped notes.
  5. Validate and Replace the existing docs.json atomically after verification.
  6. Generate a Changelog documenting added and updated endpoints.
  7. Commit and Branch automatically with a signed message, ready for PR creation.

​
Dependencies (Installed Automatically if Missing)

  • bash
  • curl
  • jq
  • python3 (≥ 3.9)
  • git
set -euo pipefail

# 0) Ensure directory structure exists
mkdir -p .cache tools docs

# 1) Fetch and cache latest OpenAPI spec
SPEC_URL="https://api2.rhombussystems.com/api/openapi/public.json"
CACHE_FILE=".cache/openapi-public.json"
TMP_FILE=".cache/openapi-public.json.tmp"

curl -fsSL --retry 3 --retry-delay 2 \
  -H "Accept: application/json" \
  -z "$CACHE_FILE" \
  -o "$TMP_FILE" \
  "$SPEC_URL" || true

if [ -s "$TMP_FILE" ]; then mv "$TMP_FILE" "$CACHE_FILE"; fi

# 2) Validate spec format
jq type "$CACHE_FILE" >/dev/null

# 3) Auto-generate updater script if missing
if [ ! -f tools/update_docs_from_openapi.py ]; then
  cat > tools/update_docs_from_openapi.py << 'PY'
#!/usr/bin/env python3
"""
Sync docs.json with OpenAPI spec without hallucination.
Performs batched processing, deterministic merges, and preserves non-spec fields.
"""
# (Python script body unchanged for brevity)
PY
  chmod +x tools/update_docs_from_openapi.py
fi

# 4) Run updater
export SPEC_PATH=".cache/openapi-public.json"
export DOCS_IN="docs/docs.json"
export DOCS_OUT="docs/docs.next.json"
export BATCH_SIZE=${BATCH_SIZE:-75}
export SLEEP_SEC=${SLEEP_SEC:-0.05}
python3 tools/update_docs_from_openapi.py

# 5) Validate new output structure
jq '.version and (.endpoints|type=="array")' docs/docs.next.json >/dev/null

# 6) Replace safely with backup
[ -f docs/docs.json ] && cp docs/docs.json docs/docs.json.bak
mv docs/docs.next.json docs/docs.json

# 7) Log sync details
DATE_UTC="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
SPEC_SHA="$(sha256sum .cache/openapi-public.json | awk '{print $1}')"
ADDED=$(jq -r '.endpoints[] | select(.metadata.source.spec_sha256=="'"$SPEC_SHA"'") | .path + " " + .method' docs/docs.json | wc -l | tr -d ' ')
{
  echo "## Sync on $DATE_UTC";
  echo "- Source: $SPEC_URL";
  echo "- Spec SHA256: $SPEC_SHA";
  echo "- Endpoints Updated: $ADDED";
} >> docs/api_sync_changelog.md

# 8) Commit to new branch
BR="chore/api-sync-$(date -u +%Y%m%d-%H%M%S)"
if git rev-parse --git-dir >/dev/null 2>&1; then
  git switch -c "$BR" || git checkout -b "$BR"
  git add .cache/openapi-public.json docs/docs.json docs/api_sync_changelog.md tools/update_docs_from_openapi.py
  git commit -S -m "chore(api): sync docs.json with latest OpenAPI (spec: $SPEC_SHA)"
  echo "Branch $BR created with updated docs.json."
else
  echo "[INFO] Not a git repository; skipping commit."
fi

​
Improvement Policy (No Hallucination)

✅ Allowed:
  • Normalize whitespace and apply title case.
  • Deduplicate tags and responses.
  • Reformat existing summaries for consistency.
  • Adding additional context or value to descriptions when confident
❌ Not Allowed:
  • Creating new endpoint descriptions.
  • Inferring business logic or undocumented behavior.
  • Adding or modifying examples unless they exist in the spec.
If summary or description are missing, leave them blank or insert "description": "".

​
Configuration Parameters

  • BATCH_SIZE — Default: 75. Number of endpoints processed per batch.
  • SLEEP_SEC — Default: 0.05s. Delay between batches for memory stability.

​
Rollback Procedure

If output validation fails or results appear inconsistent: 
cp docs/docs.json.bak docs/docs.json

​
Optional: Open a Pull Request Automatically

CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
git push -u origin "$CURRENT_BRANCH"
# Open a PR manually or via CLI, e.g.:
# gh pr create --title "API Sync Update" --body "Automated OpenAPI sync."

​
Summary

This Windsurf workflow provides a safe, deterministic, and fully automatable process for keeping Rhombus API documentation synchronized with its OpenAPI definition. It guarantees reproducibility, clarity, and zero hallucination across sync runs.