sync-openapi.yml

name: Sync OpenAPI Spec

on:
  workflow_dispatch:
    inputs:
      source_branch:
        description: "Branch to pull OpenAPI spec from in api-service repo"
        required: false
        default: "main"
      dry_run:
        description: "Dry run - do not create PR"
        required: false
        type: boolean
        default: false

permissions:
  contents: write
  pull-requests: write

jobs:
  sync-openapi:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout docs repository
        uses: actions/checkout@v4

      - name: Checkout api-service repository
        uses: actions/checkout@v4
        with:
          repository: traceloop/api-service
          token: ${{ secrets.GH_ACCESS_TOKEN }}
          path: api-service
          ref: ${{ github.event.inputs.source_branch || 'main' }}
          sparse-checkout: |
            docs/
          sparse-checkout-cone-mode: false

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

      - name: Install dependencies
        run: npm install js-yaml swagger2openapi

      - name: Read whitelist configuration
        id: config
        run: |
          # Extract source path from whitelist config using Node.js
          SOURCE_PATH=$(node -e "const yaml = require('js-yaml'); const fs = require('fs'); const config = yaml.load(fs.readFileSync('openapi-whitelist.yaml', 'utf8')); console.log(config.source.path);")
          echo "source_path=$SOURCE_PATH" >> $GITHUB_OUTPUT
          echo "Source spec path: $SOURCE_PATH"

      - name: Filter OpenAPI spec
        run: |
          SOURCE_FILE="api-service/${{ steps.config.outputs.source_path }}"

          if [ ! -f "$SOURCE_FILE" ]; then
            echo "Error: Source OpenAPI spec not found at $SOURCE_FILE"
            echo "Available files in api-service/docs/:"
            ls -la api-service/docs/ || echo "docs directory not found"
            exit 1
          fi

          echo "Filtering OpenAPI spec..."
          node scripts/filter-openapi.js \
            "$SOURCE_FILE" \
            "openapi-whitelist.yaml" \
            "openapi.json"

      - name: Generate MDX files
        run: |
          echo "Generating MDX files from OpenAPI spec..."
          npx @mintlify/scraping@latest openapi-file openapi.json -o api-reference

      - name: Update mint.json navigation
        run: |
          echo "Updating mint.json navigation..."
          node scripts/update-mint-navigation.js openapi.json

      - name: Clean up temporary files
        run: |
          rm -rf api-service node_modules package.json package-lock.json

      - name: Check for changes
        id: changes
        run: |
          # Check for any changes (new files, modified files)
          git add -A
          if git diff --cached --quiet; then
            echo "has_changes=false" >> $GITHUB_OUTPUT
            echo "No changes detected"
          else
            echo "has_changes=true" >> $GITHUB_OUTPUT
            echo "Changes detected:"
            git diff --cached --stat
          fi

      - name: Create Pull Request
        if: steps.changes.outputs.has_changes == 'true' && github.event.inputs.dry_run != 'true'
        uses: peter-evans/create-pull-request@v6
        with:
          token: ${{ secrets.GH_ACCESS_TOKEN }}
          commit-message: "docs: Update OpenAPI spec from api-service"
          title: "docs: Update OpenAPI specification"
          body: |
            ## Summary

            This PR updates the OpenAPI specification from the `api-service` repository.

            **Source:** `traceloop/api-service` @ `${{ github.event.inputs.source_branch || 'main' }}`
            **Triggered by:** @${{ github.actor }}

            ### Changes

            The OpenAPI spec has been:
            1. Pulled from the api-service repository
            2. Filtered based on the path whitelist in `openapi-whitelist.yaml`

            ### Review Checklist

            - [ ] Verify the included API endpoints are correct
            - [ ] Check that no sensitive/internal endpoints are exposed
            - [ ] Confirm Mintlify preview renders correctly

            ---
            *This PR was automatically generated by the sync-openapi workflow.*
          branch: openapi-sync/update
          delete-branch: true
          labels: |
            documentation
            automated

      - name: Summary
        run: |
          echo "## OpenAPI Sync Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          if [ "${{ steps.changes.outputs.has_changes }}" == "true" ]; then
            if [ "${{ github.event.inputs.dry_run }}" == "true" ]; then
              echo "**Status:** Changes detected (dry run - no PR created)" >> $GITHUB_STEP_SUMMARY
            else
              echo "**Status:** PR created with updated OpenAPI spec" >> $GITHUB_STEP_SUMMARY
            fi
          else
            echo "**Status:** No changes detected" >> $GITHUB_STEP_SUMMARY
          fi

          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Source branch:** ${{ github.event.inputs.source_branch || 'main' }}" >> $GITHUB_STEP_SUMMARY

          if [ -f openapi.json ]; then
            PATHS_COUNT=$(grep -c '"/' openapi.json || echo "0")
            echo "**Paths in output:** ~$PATHS_COUNT" >> $GITHUB_STEP_SUMMARY
          fi