generate-swagger.yml

name: Generate OpenAPI Specs

on:
  push:
    branches:
      - master
      - np-integrate-open-api-spex
    paths-ignore:
      - "CHANGELOG.md"
      - "**/README.md"
      - "docker/*"
      - "docker-compose/*"
  workflow_dispatch:
  release:
    types: [published]

env:
  OTP_VERSION: '27.3.4.6'
  ELIXIR_VERSION: '1.19.4'
  RELEASE_VERSION: 10.0.6

jobs:
  matrix-builder:
    name: Build matrix
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: |
          echo "matrix=$(node -e '

            // Add/remove CI matrix chain types here
            const chainTypes = [
              "default",
              "arbitrum",
              "blackfort",
              "ethereum",
              "filecoin",
              "optimism",
              "optimism-celo",
              "polygon_zkevm",
              "rsk",
              "scroll",
              "shibarium",
              "stability",
              "zetachain",
              "zilliqa",
              "zksync",
              "neon"
            ];

            const matrix = { "chain-type": ${{ 'chainTypes' }} };
            console.log(JSON.stringify(matrix));
          ')" >> $GITHUB_OUTPUT

  build-and-cache:
    name: Build and Cache deps
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: erlef/setup-beam@v1
        with:
          otp-version: ${{ env.OTP_VERSION }}
          elixir-version: ${{ env.ELIXIR_VERSION }}
          hexpm-mirrors: |
            https://builds.hex.pm
            https://cdn.jsdelivr.net/hex

      - name: "ELIXIR_VERSION.lock"
        run: echo "${ELIXIR_VERSION}" > ELIXIR_VERSION.lock

      - name: "OTP_VERSION.lock"
        run: echo "${OTP_VERSION}" > OTP_VERSION.lock

      - name: Restore Mix Deps Cache
        uses: actions/cache@v4
        id: deps-cache
        with:
          path: |
            deps
            _build
          key: ${{ runner.os }}-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-${{ env.MIX_ENV }}-deps-mixlockhash-${{ hashFiles('mix.lock') }}
          restore-keys: |
            ${{ runner.os }}-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-${{ env.MIX_ENV }}-deps-mixlockhash-

      - name: Conditionally build Mix deps cache
        if: steps.deps-cache.outputs.cache-hit != 'true'
        run: |
          mix local.hex --force
          mix local.rebar --force
          mix deps.get
          mix deps.compile --skip-umbrella-children

  generate-swagger:
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.matrix-builder.outputs.matrix) }}
    name: Generate Open API spec
    runs-on: ubuntu-latest
    needs:
      - build-and-cache
      - matrix-builder
    steps:
      - uses: actions/checkout@v5
      - uses: erlef/setup-beam@v1
        with:
          otp-version: ${{ env.OTP_VERSION }}
          elixir-version: ${{ env.ELIXIR_VERSION }}
          hexpm-mirrors: |
            https://builds.hex.pm
            https://cdn.jsdelivr.net/hex

      - name: Mix Deps Cache
        uses: actions/cache/restore@v4
        id: deps-cache
        with:
          path: |
            deps
            _build
          key: ${{ runner.os }}-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-${{ env.MIX_ENV }}-deps-mixlockhash-${{ hashFiles('mix.lock') }}
          restore-keys: |
            ${{ runner.os }}-${{ env.ELIXIR_VERSION }}-${{ env.OTP_VERSION }}-${{ env.MIX_ENV }}-deps-mixlockhash-

      - name: mix openapi.spec.yaml
        run: |
          mix openapi.spec.yaml --spec BlockScoutWeb.Specs.Public openapi.${{ matrix.chain-type }}.yaml --start-app=false
        env:
          CHAIN_TYPE: ${{ matrix.chain-type != 'default' && matrix.chain-type || '' }}
          MUD_INDEXER_ENABLED: false

      - name: Generate MUD-enabled spec for Optimism
        if: matrix.chain-type == 'optimism'
        run: |
          mix openapi.spec.yaml --spec BlockScoutWeb.Specs.Public openapi.mud.yaml --start-app=false
        env:
          CHAIN_TYPE: optimism
          MUD_INDEXER_ENABLED: true

      - name: Upload OpenAPI spec
        uses: actions/upload-artifact@v4
        with:
          name: openapi-spec-${{ matrix.chain-type }}
          path: openapi.${{ matrix.chain-type }}.yaml
          retention-days: 1

      - name: Upload MUD-enabled spec
        if: matrix.chain-type == 'optimism'
        uses: actions/upload-artifact@v4
        with:
          name: openapi-spec-mud
          path: openapi.mud.yaml
          retention-days: 1

  push-specs:
    needs: 
      - generate-swagger
      - matrix-builder
    runs-on: ubuntu-latest
    name: Push all OpenAPI specs
    steps:
      - name: Validate required secrets
        run: |
          if [ -z "${{ secrets.API_SPECS_PAT }}" ]; then
            echo "Error: API_SPECS_PAT secret is not set"
            exit 1
          fi

      - name: Checkout specs repository
        uses: actions/checkout@v5
        with:
          repository: ${{ vars.API_SPECS_REPOSITORY }}
          token: ${{ secrets.API_SPECS_PAT }}
          path: api-specs

      - name: Download all swagger specs
        uses: actions/download-artifact@v5
        with:
          pattern: openapi-spec-*
          merge-multiple: true
          path: temp-specs

      - name: Merge all OpenAPI specs into all-in-one spec
        run: |
          npm install js-yaml
          cat > merge-specs.js << 'SCRIPT_EOF'
          const fs = require('fs');
          const path = require('path');
          const yaml = require('js-yaml');

          const specDir = './temp-specs';
          const outputFile = path.join(specDir, 'openapi.all.yaml');

          const files = fs.readdirSync(specDir)
            .filter(f => f.endsWith('.yaml'))
            .sort();

          let merged = null;

          for (const file of files) {
            const content = yaml.load(fs.readFileSync(path.join(specDir, file), 'utf8'));
            if (!merged) {
              merged = JSON.parse(JSON.stringify(content));
              continue;
            }
            // Union merge paths (first definition wins for duplicates)
            if (content.paths) {
              merged.paths = merged.paths || {};
              for (const [p, def] of Object.entries(content.paths)) {
                if (!merged.paths[p]) {
                  merged.paths[p] = def;
                }
              }
            }
            // Union merge components (first definition wins for duplicates)
            if (content.components) {
              merged.components = merged.components || {};
              for (const [section, defs] of Object.entries(content.components)) {
                if (!merged.components[section]) {
                  merged.components[section] = defs;
                } else {
                  for (const [name, def] of Object.entries(defs)) {
                    if (!merged.components[section][name]) {
                      merged.components[section][name] = def;
                    }
                  }
                }
              }
            }
            // Union merge tags (by name)
            if (content.tags) {
              merged.tags = merged.tags || [];
              const existingTagNames = new Set(merged.tags.map(t => t.name));
              for (const tag of content.tags) {
                if (!existingTagNames.has(tag.name)) {
                  merged.tags.push(tag);
                  existingTagNames.add(tag.name);
                }
              }
            }
          }

          fs.writeFileSync(outputFile, yaml.dump(merged, { lineWidth: -1 }));
          console.log(`Merged ${files.length} specs into ${outputFile}`);
          SCRIPT_EOF
          node merge-specs.js

      - name: Create specs directory structure
        run: |
          VERSION=${{ github.event_name == 'release' && env.RELEASE_VERSION || 'master' }}

          for SPEC_FILE in temp-specs/*; do
            if [ -f "$SPEC_FILE" ]; then
              FILENAME=$(basename "$SPEC_FILE")
              
              # Handle MUD spec specially
              if [ "$FILENAME" = "openapi.mud.yaml" ]; then
                mkdir -p "api-specs/blockscout/${VERSION}/mud"
                cp "$SPEC_FILE" "api-specs/blockscout/${VERSION}/mud/swagger.yaml"
              else
                # Extract chain type from filename (openapi.CHAINTYPE.yaml)
                CHAIN_TYPE=$(echo "$FILENAME" | sed 's/openapi\.\(.*\)\.yaml/\1/')
                mkdir -p "api-specs/blockscout/${VERSION}/${CHAIN_TYPE}"
                cp "$SPEC_FILE" "api-specs/blockscout/${VERSION}/${CHAIN_TYPE}/swagger.yaml"
              fi
            fi
          done


      - name: Commit and push changes
        working-directory: api-specs
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          
          git add .

          # Only commit if there are changes
          if git diff --staged --quiet; then
            echo "No changes to commit"
          else
            git commit -m "[SKIP-GH-PAGES] create OpenAPI specs for Blockscout ${{ github.event_name == 'release' && env.RELEASE_VERSION || github.sha }}"
            git push
          fi

      - name: Clean up
        if: always()
        run: |
          rm -rf temp-specs
          rm -rf api-specs