update-docs.yaml

name: Update API Documentation

on:
  # Trigger on pushes to main branch (when API changes)
  push:
    branches: [main]
    paths:
      - "app/**"
  workflow_dispatch: # Allow manual triggering of the workflow

permissions:
  contents: write

jobs:
  update-docs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.12"

      - name: Install Python dependencies
        run: |
          python -m pip install --upgrade pip
          pip install .

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Start API server
        run: |
          # Start the API in the background
          uvicorn app.main:app --host 0.0.0.0 --port 5000 &
          API_PID=$!
          echo "API_PID=$API_PID" >> $GITHUB_ENV

          # Wait for API to be ready
          echo "Waiting for API to be ready..."
          for i in {1..30}; do
            if curl -f http://localhost:5000/docs > /dev/null 2>&1; then
              echo "API is ready!"
              break
            fi
            echo "Attempt $i: API not ready yet, waiting..."
            sleep 2
          done

          # Verify API is responding
          if ! curl -f http://localhost:5000/docs > /dev/null 2>&1; then
            echo "Error: API failed to start"
            exit 1
          fi

      - name: Download OpenAPI spec
        run: |
          # Create docs directory if it doesn't exist
          mkdir -p docs

          # Download the OpenAPI spec
          curl -o docs/openapi.json http://localhost:5000/openapi.json

          # Verify the file was downloaded and is valid JSON
          if [ ! -f "docs/openapi.json" ]; then
            echo "Error: Failed to download openapi.json"
            exit 1
          fi

          # Basic JSON validation
          if ! python -m json.tool docs/openapi.json > /dev/null; then
            echo "Error: Downloaded file is not valid JSON"
            exit 1
          fi

          echo "Successfully downloaded OpenAPI spec"

      - name: Generate HTML documentation
        run: |
          # Install and use redocly CLI
          npx @redocly/cli build-docs docs/openapi.json --output docs/index.html

          # Verify HTML was generated
          if [ ! -f "docs/index.html" ]; then
            echo "Error: Failed to generate HTML documentation"
            exit 1
          fi

          echo "Successfully generated HTML documentation"

      - name: Stop API server
        if: always()
        run: |
          if [ -n "$API_PID" ]; then
            kill $API_PID || true
          fi

      - name: Check for changes
        id: check_changes
        run: |
          # Check if there are any changes to commit
          if git diff --quiet docs/; then
            echo "No changes detected in documentation"
            echo "changes=false" >> $GITHUB_OUTPUT
          else
            echo "Changes detected in documentation"
            echo "changes=true" >> $GITHUB_OUTPUT
          fi

      - name: Commit and push changes
        if: steps.check_changes.outputs.changes == 'true'
        run: |
          # Configure git
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

          # Add and commit changes
          git add docs/openapi.json docs/index.html
          git commit -m "docs: update API documentation [automated]

          - Updated OpenAPI specification
          - Regenerated HTML documentation

          Generated by GitHub Actions on $(date -u '+%Y-%m-%d %H:%M:%S UTC')"

          # Push changes
          git push

      - name: Create summary
        run: |
          echo "## API Documentation Update Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          if [ "${{ steps.check_changes.outputs.changes }}" == "true" ]; then
            echo "✅ Documentation updated successfully" >> $GITHUB_STEP_SUMMARY
            echo "- OpenAPI spec downloaded from API" >> $GITHUB_STEP_SUMMARY
            echo "- HTML documentation regenerated" >> $GITHUB_STEP_SUMMARY
            echo "- Changes committed and pushed to main branch" >> $GITHUB_STEP_SUMMARY
          else
            echo "ℹ️ No changes detected in documentation" >> $GITHUB_STEP_SUMMARY
          fi