ISSUE-344: api doc

Author: tatevikg1

.github/workflows/restapi-docs.yml

@@ -0,0 +1,83 @@
+name: Publish Core Docs
+on: [push, pull_request]
+jobs:
+  make-restapi-docs:
+    name: Checkout phpList core and generate docs using `openapi`
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout
+        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: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_ENV
+      - name: Cache composer dependencies
+        uses: actions/cache@v3
+        with:
+          path: ${{ env.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+      - name: Install current dependencies from composer.lock
+        run: composer install --no-interaction --prefer-dist
+      - name: Generate OpenAPI documentation
+        run: php vendor/bin/openapi --output docs/openapi.json src/
+      - name: Zip OpenAPI documentation
+        run: zip -r openapi-docs.zip docs/openapi.json
+      - name: Upload generated doc files
+        uses: actions/upload-artifact@v4
+        with:
+          name: doc-files
+          path: openapi-docs.zip
+
+  deploy-docs:
+    name: Deploy Core Docs
+    runs-on: ubuntu-20.04
+    needs: make-restapi-docs
+    steps:
+      - name: Checkout phplist/core-docs
+        uses: actions/checkout@v3
+        with:
+          repository: phpList/core-docs
+          fetch-depth: 0
+          token: ${{ secrets.PUSH_CORE_DOCS }}
+      - name: Restore OpenAPI Spec
+        uses: actions/download-artifact@v4
+        with:
+          name: doc-files
+      - name: Unzip OpenAPI documentation
+        run: |
+          unzip openapi-docs.zip
+          rm openapi-docs.zip
+      - name: List Files
+        run: ls
+      - name: Sync old files with newly generated ones
+        run: rsync -av docs/openapi.json .
+      - name: Remove temporary directories
+        run: rm -rf docs
+      - name: Check if updates/changes
+        run: git status --porcelain > repo-changes.txt
+      - name: Check changes file
+        run: cat repo-changes.txt
+      - name: Verify updates
+        id: allow-deploy
+        run: |
+          if [ -s repo-changes.txt ]; then 
+            echo "Updates made to documentation"; 
+            echo 'DEPLOY=true' >> $GITHUB_ENV; 
+          else 
+            echo "No updates made to documentation. Deployment would be skipped."; 
+            echo 'DEPLOY=false' >> $GITHUB_ENV; 
+          fi
+      - name: Commit changes and deploy
+        if: ${{ env.DEPLOY == 'true' }}
+        run: |
+          rm repo-changes.txt
+          git config user.name "github-actions"
+          git config user.email "[email protected]"
+          git add .
+          git commit -s -m "phplist/core docs deployment `date`"
+          git push origin main --force

composer.json

@@ -31,7 +31,7 @@
     },
     "require": {
         "php": "^8.1",
-        "phplist/core": "dev-ISSUE-337",
+        "phplist/core": "dev-main",
         "friendsofsymfony/rest-bundle": "*",
         "symfony/test-pack": "^1.0",
         "symfony/process": "^6.4",

src/Controller/SubscriberController.php

@@ -39,7 +39,7 @@ public function __construct(
 
     #[Route('/subscribers', name: 'create_subscriber', methods: ['POST'])]
     #[OA\Post(
-        path: '/subscriber',
+        path: '/subscribers',
         description: 'Creates a new subscriber (if there is no subscriber with the given email address yet).',
         summary: 'Create a subscriber',
         requestBody: new OA\RequestBody(