merge main

Author: tatevikg1

.github/CONTRIBUTING.md

@@ -60,13 +60,43 @@ have a chance of keeping on top of things:
 8. Add a changelog entry.
 9. [Commit](#git-commits) and push your changes.
 10. [Create a pull request](https://help.github.com/articles/about-pull-requests/)
-    for your changes. Check that the Travis build is green. (If it is not, fix the
-    problems listed by Travis.)
+    for your changes. Check that the [Github actions](https://github.com/phpList/rest-api/actions/workflows/ci.yml) build is green. (If it is not, fix the
+    problems listed by [Github actions](https://github.com/phpList/rest-api/actions/workflows/ci.yml).)
     We have provided a template for pull requests as well.
 11. [Request a review](https://help.github.com/articles/about-pull-request-reviews/).
 11. Together with your reviewer, polish your changes until they are ready to be
     merged.
 
+## API Documenting with `OPENAPI`
+
+Controllers are annotated with the [`OpenAPI`](https://swagger.io/docs/specification/about/) specification using the `PHPDoc` implementation from [zircote/swagger-php](https://github.com/zircote/swagger-php). 
+
+If you add or modify existing annotations, you should run `composer openapi-generate` to have the updated openapi decription of the API.
+
+### Notes
+- `composer openapi-generate` produces `openapi.json` in `docs/`
+-  The generated `docs/openapi.json` is excluded in commits. _See .gitignore_
+-  The only reason you should generate `openapi.json` is for debugging and testing.
+
+### Debugging `openapi.json` description.
+
+To ensure builds pass and new annotations are deployed, do validate `openapi.json` by copy-pasting it's content in `https://validator.swagger.io/`
+
+In addition you can also use the [openapi-checker](github.com/phplist/openapi-checker) to validate you file as follows;
+
+- `npm install -g openapi-checker`
+- `openapi-checker docs/openapi.json`
+
+### More on `composer openapi-generate` 
+
+`composer openapi-generate` basically runs `vendor/bin/openapi -o docs/openapi.json --format json src` defined in the scripts section of `composer.json` which as mentioned above generates `openapi.json` description file in the `docs/` directory.
+
+### Swagger UI
+
+[Swagger UI](https://github.com/swagger-api/swagger-ui) is used to visualize generated api description and is visible at [phplist.github.io/restapi-docs](https://phplist.github.io/restapi-docs) after a successful CI build.
+
+You might also achieve local visualization by cloning [phplist/restapi-docs](https://github.com/phpList/restapi-docs) and temporally changing the `url` property of `SwaggerUIBundle` to point to your generated file.
+
 
 ## Unit-test your changes
 

.github/workflows/ci.yml

@@ -48,22 +48,29 @@ jobs:
           # key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
           key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
           restore-keys: ${{ runner.os }}-composer-
-      - name: Install the lowest dependencies
-        run: composer update --with-dependencies --prefer-stable --prefer-dist --prefer-lowest
+      - name: Install dependencies
+        run: composer update --with-dependencies --prefer-stable --prefer-dist
         if: ${{ matrix.dependencies }} == "latest"
       - name: Install current dependencies from composer.lock
         run: composer install
-        if: ${{ matrix.dependencies }} == "oldest"
       - name: Set up database schema
         run: mysql --host 127.0.0.1 --port ${{ job.services.mysql.ports['3306'] }} -u${{ env.DB_USERNAME }} -p${{ env.DB_PASSWORD }} ${{ env.DB_DATABASE }} < vendor/phplist/core/resources/Database/Schema.sql
       - name: Validating composer.json
         run: composer validate --no-check-all --no-check-lock --strict;
       - name: Linting all php files
         run: find src/ tests/ public/ -name ''*.php'' -print0 | xargs -0 -n 1 -P 4 php -l; php -l;
-      - name: Run integration tests with phpunit
-        run: vendor/bin/phpunit tests/Integration/
-      - name: Running the system tests
-        run: vendor/bin/phpunit tests/System/;
+      - name: Running  unit tests
+        run: vendor/bin/phpunit tests/Unit/;
+        continue-on-error: ${{matrix.php-versions == '8.0' }} # [temp-php8]
+      - name: Running the integration tests
+        run: | 
+          export PHPLIST_DATABASE_NAME=${{ env.DB_DATABASE }}
+          export PHPLIST_DATABASE_USER=${{ env.DB_USERNAME }}
+          export PHPLIST_DATABASE_PASSWORD=${{ env.DB_PASSWORD }}
+          export PHPLIST_DATABASE_PORT=${{ job.services.mysql.ports['3306'] }}
+          export PHPLIST_DATABASE_HOST=127.0.0.1
+          vendor/bin/phpunit tests/Integration/
+        continue-on-error: ${{matrix.php-versions == '8.0' }} # [temp-php8]
       - name: Running static analysis
         run: vendor/bin/phpstan analyse -l 5 src/ tests/;
       - name: Running PHPMD

.gitignore

@@ -9,6 +9,7 @@
 /config/config_modules.yml
 /config/parameters.yml
 /config/routing_modules.yml
+/docs/openapi.json
 /nbproject
 /public/
 /var/

README.md

@@ -40,6 +40,8 @@ which also has more detailed installation instructions in the README.
 
 Visit `/docs` endpoint to access the full interactive documentation for `phpList/rest-api`.
 
+Look at the **"API Documentation with Swagger"** section in the [contribution guide](.github/CONTRIBUTING.md) for more information on API documenation.
+
 ## Local demo with Postman
 
 You can try out the API using pre-prepared requests and the Postman GUI 

composer.json

@@ -13,10 +13,15 @@
     "homepage": "https://www.phplist.com/",
     "license": "AGPL-3.0-or-later",
     "authors": [
+        {
+            "name": "Xheni Myrtaj",
+            "email": "xheni@phplist.com",
+            "role": "Maintainer"
+        },
         {
             "name": "Oliver Klee",
             "email": "oliver@phplist.com",
-            "role": "Developer"
+            "role": "Former developer"
         }
     ],
     "support": {
@@ -90,7 +95,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-ISSUE-337": "5.0.x-dev"
+            "dev-master": "5.0.x-dev"
         },
         "symfony-app-dir": "bin",
         "symfony-bin-dir": "bin",