restapi-docs.yml

name: Publish REST API Docs
on:
  push:
    branches:
      - main
  pull_request:

jobs:
  make-restapi-docs:
    name: Checkout phpList rest-api and generate docs specification (OpenAPI latest-restapi.json)
    runs-on: ubuntu-20.04
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Setup PHP with Composer and Extensions
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.1
          extensions: mbstring, dom, fileinfo, mysql

      - name: Cache Composer Dependencies
        uses: actions/cache@v3
        with:
          path: ~/.composer/cache
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: |
            ${{ runner.os }}-composer-

      - name: Install Composer Dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Generate OpenAPI Specification JSON
        run: vendor/bin/openapi -o docs/latest-restapi.json --format json src

      - name: Upload REST API Specification
        uses: actions/upload-artifact@v3
        with:
          name: restapi-json
          path: docs/latest-restapi.json

  deploy-docs:
    name: Deploy REST API Specification
    runs-on: ubuntu-20.04
    needs: make-restapi-docs
    steps:
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 14

      - name: Install openapi-checker
        run: npm install -g openapi-checker

      - name: Checkout REST API Docs Repository
        uses: actions/checkout@v3
        with:
          repository: phpList/restapi-docs
          fetch-depth: 0
          token: ${{ secrets.PUSH_REST_API_DOCS }}

      - name: Download Generated REST API Specification
        uses: actions/download-artifact@v3
        with:
          name: restapi-json

      - name: Validate OpenAPI Specification
        run: openapi-checker docs/latest-restapi.json

      - name: Compare Specifications
        run: git diff --no-index --output=restapi-diff.txt docs/latest-restapi.json restapi.json || true

      - name: Check Differences and Decide Deployment
        id: allow-deploy
        run: |
          if [ -s restapi-diff.txt ]; then 
            echo "Updates detected in the REST API specification. Proceeding with deployment.";
            echo 'DEPLOY=true' >> $GITHUB_ENV;
          else 
            echo "No changes detected in the REST API specification. Skipping deployment.";
            echo 'DEPLOY=false' >> $GITHUB_ENV;
          fi

      - name: Commit and Deploy Updates
        if: env.DEPLOY == 'true'
        run: |
          mv docs/latest-restapi.json docs/restapi.json
          git config user.name "github-actions"
          git config user.email "github-actions@restapi-docs.workflow"
          git add docs/restapi.json
          git commit -m "Update REST API documentation `date`"
          git push