phplist-api-client swagger push ci (#151)

* phplist-api-client swagger push ci

* swagger updates

* swagger route name fix

---------

Co-authored-by: Tatevik <[email protected]>

Author: TatevikGr

.github/workflows/client-docs.yml

@@ -0,0 +1,87 @@
+name: Update phplist-api-client OpenAPI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  generate-openapi:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout Source 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 OpenAPI Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-json
+          path: docs/latest-restapi.json
+
+  update-phplist-api-client:
+    runs-on: ubuntu-22.04
+    needs: generate-openapi
+    steps:
+      - name: Checkout phplist-api-client Repository
+        uses: actions/checkout@v3
+        with:
+          repository: TatevikGr/phplist-api-client
+          token: ${{ secrets.PUSH_API_CLIENT }}
+          fetch-depth: 0
+
+      - name: Download Generated OpenAPI JSON
+        uses: actions/download-artifact@v4
+        with:
+          name: openapi-json
+          path: ./new-openapi
+
+      - name: Compare and Check for Differences
+        id: diff
+        run: |
+          # Compare the openapi files if old exists, else always deploy
+          if [ -f openapi.json ]; then
+            diff openapi.json new-openapi/latest-restapi.json > openapi-diff.txt || true
+            if [ -s openapi-diff.txt ]; then
+              echo "diff=true" >> $GITHUB_OUTPUT
+            else
+              echo "diff=false" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "No previous openapi.json, will add."
+            echo "diff=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Update and Commit OpenAPI File
+        if: steps.diff.outputs.diff == 'true'
+        run: |
+          cp new-openapi/latest-restapi.json openapi.json
+          git config user.name "github-actions"
+          git config user.email "[email protected]"
+          git add openapi.json
+          git commit -m "Update openapi.json from REST API workflow `date`"
+          git push
+
+      - name: Skip Commit if No Changes
+        if: steps.diff.outputs.diff == 'false'
+        run: echo "No changes to openapi.json, skipping commit."

src/Common/SwaggerSchemasResponse.php

@@ -23,7 +23,7 @@
         new OA\Property(
             property: 'message',
             type: 'string',
-            example: 'Some fields invalid: email, confirmed, html_email'
+            example: 'Some fields are invalid'
         )
     ],
     type: 'object'

src/Identity/Controller/AdministratorController.php

@@ -133,7 +133,7 @@ public function getAdministrators(Request $request): JsonResponse
                 content: new OA\JsonContent(ref: '#/components/schemas/Administrator')
             ),
             new OA\Response(
-                response: 400,
+                response: 422,
                 description: 'Invalid input'
             )
         ]
@@ -234,7 +234,8 @@ public function getAdministrator(
         responses: [
             new OA\Response(
                 response: 200,
-                description: 'Administrator updated successfully'
+                description: 'Administrator updated successfully',
+                content: new OA\JsonContent(ref: '#/components/schemas/Administrator')
             ),
             new OA\Response(
                 response: 404,

src/Subscription/Controller/SubscriberAttributeDefinitionController.php

@@ -42,7 +42,7 @@ public function __construct(
 
     #[Route('', name: 'create', methods: ['POST'])]
     #[OA\Post(
-        path: '/api/v2/subscriber/attributes',
+        path: '/api/v2/subscribers/attributes',
         description: '🚧 **Status: Beta** – This method is under development. Avoid using in production. ' .
             'Returns created subscriber attribute definition.',
         summary: 'Create a subscriber attribute definition.',
@@ -94,7 +94,7 @@ public function create(Request $request): JsonResponse
 
     #[Route('/{definitionId}', name: 'update', requirements: ['definitionId' => '\d+'], methods: ['PUT'])]
     #[OA\Put(
-        path: '/api/v2/subscriber/attributes/{definitionId}',
+        path: '/api/v2/subscribers/attributes/{definitionId}',
         description: '🚧 **Status: Beta** – This method is under development. Avoid using in production. ' .
             'Returns updated subscriber attribute definition.',
         summary: 'Update a subscriber attribute definition.',
@@ -161,7 +161,7 @@ public function update(
 
     #[Route('/{definitionId}', name: 'delete', requirements: ['definitionId' => '\d+'], methods: ['DELETE'])]
     #[OA\Delete(
-        path: '/api/v2/subscriber/attributes/{definitionId}',
+        path: '/api/v2/subscribers/attributes/{definitionId}',
         description: '🚧 **Status: Beta** – This method is under development. Avoid using in production. ' .
             'Deletes a single subscriber attribute definition.',
         summary: 'Deletes an attribute definition.',
@@ -215,7 +215,7 @@ public function delete(
 
     #[Route('', name: 'get_list', methods: ['GET'])]
     #[OA\Get(
-        path: '/api/v2/subscriber/attributes',
+        path: '/api/v2/subscribers/attributes',
         description: '🚧 **Status: Beta** – This method is under development. Avoid using in production. ' .
             'Returns a JSON list of all subscriber attribute definitions.',
         summary: 'Gets a list of all subscriber attribute definitions.',
@@ -282,7 +282,7 @@ public function getPaginated(Request $request): JsonResponse
 
     #[Route('/{definitionId}', name: 'get_one', requirements: ['definitionId' => '\d+'], methods: ['GET'])]
     #[OA\Get(
-        path: '/api/v2/subscriber/attributes/{definitionId}',
+        path: '/api/v2/subscribers/attributes/{definitionId}',
         description: '🚧 **Status: Beta** – This method is under development. Avoid using in production. ' .
             'Returns a single attribute with specified ID.',
         summary: 'Gets attribute with specified ID.',