Update API Documentation #2
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |