OpenAPI Sync #17
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: OpenAPI Sync | |
| on: | |
| # Manual trigger | |
| workflow_dispatch: | |
| inputs: | |
| source: | |
| description: 'Source to regenerate (leave empty for all)' | |
| required: false | |
| type: string | |
| # Webhook trigger from source repositories | |
| repository_dispatch: | |
| types: [openapi-update] | |
| # Scheduled daily sync | |
| schedule: | |
| - cron: '0 6 * * *' # 6 AM UTC daily | |
| jobs: | |
| generate-openapi: | |
| name: Generate OpenAPI Specifications | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| pull-requests: write | |
| steps: | |
| - name: Checkout documentation repository | |
| uses: actions/checkout@v4 | |
| with: | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| fetch-depth: 0 | |
| - name: Set up Python | |
| uses: actions/setup-python@v4 | |
| with: | |
| python-version: '3.11' | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install pyyaml requests protobuf grpcio-tools | |
| - name: Install protoc and grpc-gateway tools | |
| run: | | |
| # Install protoc | |
| PROTOC_VERSION=23.4 | |
| wget https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOC_VERSION}/protoc-${PROTOC_VERSION}-linux-x86_64.zip | |
| unzip protoc-${PROTOC_VERSION}-linux-x86_64.zip -d /tmp/protoc | |
| sudo mv /tmp/protoc/bin/protoc /usr/local/bin/ | |
| sudo mv /tmp/protoc/include/* /usr/local/include/ | |
| # Install grpc-gateway protoc plugins | |
| go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest | |
| go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest | |
| go install google.golang.org/protobuf/cmd/protoc-gen-go@latest | |
| go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest | |
| - name: Configure Git | |
| run: | | |
| git config --local user.email "[email protected]" | |
| git config --local user.name "GitHub Action" | |
| - name: Verify webhook signature (if webhook triggered) | |
| if: github.event_name == 'repository_dispatch' | |
| env: | |
| WEBHOOK_SECRET: ${{ secrets.OPENAPI_WEBHOOK_SECRET }} | |
| run: | | |
| # Verify webhook signature for security | |
| echo "Webhook triggered by: ${{ github.event.client_payload.repository }}" | |
| # Add signature verification logic here | |
| - name: Determine sources to update | |
| id: sources | |
| run: | | |
| if [ "${{ github.event_name }}" == "repository_dispatch" ]; then | |
| # Webhook triggered - determine source from payload | |
| SOURCE="${{ github.event.client_payload.source || 'all' }}" | |
| elif [ "${{ github.event.inputs.source }}" != "" ]; then | |
| # Manual trigger with specific source | |
| SOURCE="${{ github.event.inputs.source }}" | |
| else | |
| # Scheduled or manual trigger without source - update all | |
| SOURCE="all" | |
| fi | |
| echo "source=${SOURCE}" >> $GITHUB_OUTPUT | |
| echo "Updating source: ${SOURCE}" | |
| - name: Generate OpenAPI specifications | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| python scripts/openapi-gen/generate.py \ | |
| --config scripts/openapi-gen/config.yaml \ | |
| ${{ steps.sources.outputs.source != 'all' && format('--source {0}', steps.sources.outputs.source) || '' }} | |
| - name: Run Mintlify scraper to generate MDX files | |
| run: | | |
| # Install Mintlify CLI | |
| npm install -g @mintlify/scraping | |
| # Generate MDX files for each OpenAPI spec | |
| for spec in docs/api-specs/*.json; do | |
| if [ -f "$spec" ]; then | |
| echo "Generating MDX files for $spec" | |
| output_dir="docs/api-reference/$(basename "$spec" .json)" | |
| npx @mintlify/scraping@latest openapi-file "$spec" -o "$output_dir" | |
| fi | |
| done | |
| - name: Update navigation in docs.json | |
| run: | | |
| python scripts/openapi-gen/update-navigation.py | |
| - name: Check for changes | |
| id: changes | |
| run: | | |
| git add . | |
| if git diff --staged --quiet; then | |
| echo "changed=false" >> $GITHUB_OUTPUT | |
| echo "No changes detected" | |
| else | |
| echo "changed=true" >> $GITHUB_OUTPUT | |
| echo "Changes detected" | |
| git diff --staged --name-only | |
| fi | |
| - name: Create Pull Request | |
| if: steps.changes.outputs.changed == 'true' | |
| uses: peter-evans/create-pull-request@v5 | |
| with: | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| commit-message: | | |
| feat: update OpenAPI specifications | |
| Auto-generated by OpenAPI sync workflow | |
| Source: ${{ steps.sources.outputs.source }} | |
| Triggered by: ${{ github.event_name }} | |
| title: "🔄 Update OpenAPI Specifications" | |
| body: | | |
| ## OpenAPI Sync Update | |
| This PR contains automatically generated updates to the OpenAPI specifications and documentation. | |
| **Details:** | |
| - **Source**: ${{ steps.sources.outputs.source }} | |
| - **Trigger**: ${{ github.event_name }} | |
| - **Timestamp**: ${{ github.event.head_commit.timestamp || github.run_id }} | |
| **Changes include:** | |
| - Updated OpenAPI specifications in `docs/api-specs/` | |
| - Generated/updated MDX pages in `docs/api-reference/` | |
| - Updated navigation structure in `docs.json` | |
| **Review checklist:** | |
| - [ ] Verify API endpoints are correctly documented | |
| - [ ] Check code examples render properly | |
| - [ ] Ensure navigation structure is logical | |
| - [ ] Test interactive API playground functionality | |
| > This PR was automatically created by the OpenAPI sync workflow. | |
| branch: openapi-sync/${{ github.run_id }} | |
| delete-branch: true | |
| labels: | | |
| automated | |
| documentation | |
| api | |
| - name: Auto-merge if minor changes | |
| if: steps.changes.outputs.changed == 'true' && github.event_name == 'schedule' | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| # For scheduled runs, auto-merge if changes are minimal | |
| # This could include logic to check if only certain files changed | |
| echo "Scheduled update - consider auto-merging after validation" | |
| - name: Notify on failure | |
| if: failure() | |
| uses: 8398a7/action-slack@v3 | |
| with: | |
| status: failure | |
| text: | | |
| OpenAPI sync workflow failed | |
| Repository: ${{ github.repository }} | |
| Source: ${{ steps.sources.outputs.source }} | |
| Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} | |
| env: | |
| SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} | |
| - name: Summary | |
| if: always() | |
| run: | | |
| echo "## OpenAPI Sync Summary" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Source**: ${{ steps.sources.outputs.source }}" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Trigger**: ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Changes**: ${{ steps.changes.outputs.changed }}" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Status**: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY |