ISSUE-344: add docs workflow

Author: tatevikg1

.github/workflows/restapi-docs.yml

@@ -0,0 +1,93 @@
+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 swagger-cli
+
+      - 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
+          path: docs
+
+      - name: Validate OpenAPI Specification
+        run: swagger-cli validate 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 "[email protected]"
+          git add docs/restapi.json
+          git commit -m "Update REST API documentation `date`"
+          git push