Add Contributing.md (zircote#1412)

Author: DerManoMann

CONTRIBUTING.md

@@ -0,0 +1,83 @@
+## Contributing
+
+Contributions of any kind are welcome.
+
+Feel free to submit [Github Issues](https://github.com/zircote/swagger-php/issues)
+or [pull requests](https://github.com/zircote/swagger-php/pulls).
+
+
+## Quick Guide
+
+The documentation site has [some details](https://zircote.github.io/swagger-php/guide/under-the-hood.html#documentation) about internals.
+
+### How-To
+
+* [Fork](https://help.github.com/articles/fork-a-repo/) the repo.
+* [Checkout](https://git-scm.com/docs/git-checkout) the branch you want to make changes on.
+    * Typically, this will be `master`. Note that most of the time, `master` represents the next release of swagger-php, so Pull Requests that break backwards compatibility might be postponed.
+* Install dependencies: `composer install`.
+* Create a new branch, e.g. `feature-foo` or `bugfix-bar`.
+* Make changes.
+* If you are adding functionality or fixing a bug - add a test!
+
+  Prefer adding new test cases over modifying existing ones.
+* Update documentation: `composer docs:gen`.
+* Run static analysis using PHPStan/Psalm: `composer analyse`.
+* Check if tests pass: `composer test`.
+* Fix code style issues: `composer cs`.
+
+
+## Documentation
+
+The documentation website is build from the [docs](docs/) folder with [vitepress](https://vitepress.vuejs.org).
+This process involves converting the existing markdown (`.md`) files into static HTML pages and publishing them.
+
+Some reference content is based on the existing code, so changes to annotations, attributes and processors will require to re-generate those markdown files: `composer docs:gen`.
+
+The actual published content is managed in the [gh-pages](https://github.com/zircote/swagger-php/tree/gh-pages)  branch and driven by a [publish action](https://github.com/zircote/swagger-php/actions/workflows/gh-pages.yml).
+
+
+## Useful commands
+
+### To run both unit tests and linting execute
+```shell
+composer test
+```
+
+### To run static-analysis execute
+```shell
+composer analyse
+```
+
+### Running unit tests only
+```shell
+./bin/phpunit
+```
+
+### Regenerate reference markup docs
+```shell
+composer docs:gen
+```
+
+### Running linting only
+```shell
+composer lint
+```
+
+### To make `php-cs-fixer` fix linting errors
+```shell
+composer cs
+```
+
+### Run dev server for local development of `gh-pages`
+```shell
+composer docs:dev
+```
+
+
+## Project's Standards
+
+* [PSR-1: Basic Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)
+* [PSR-2: Coding Style Guide](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
+* [PSR-4: Autoloading Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md)
+* [PSR-5: PHPDoc (draft)](https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md)

README.md

@@ -31,13 +31,13 @@ Programmatically, the method `Generator::setVersion()` can be used to change the
 
 ## Installation (with [Composer](https://getcomposer.org))
 
-```bash
+```shell
 composer require zircote/swagger-php
 ```
 
 For cli usage from anywhere install swagger-php globally and make sure to place the `~/.composer/vendor/bin` directory in your PATH so the `openapi` executable can be located by your system.
 
-```bash
+```shell
 composer global require zircote/swagger-php
 ```
 
@@ -77,7 +77,7 @@ Documentation of how to use the `Generator` class can be found in the [Generator
 
 The `openapi` command line interface can be used to generate the documentation to a static yaml/json file.
 
-```bash
+```shell
 ./vendor/bin/openapi --help
 ```
 Starting with version 4 the default analyser used on the command line is the new `ReflectionAnalyser`.
@@ -98,13 +98,7 @@ $openapi = $serializer->deserialize($jsonString, 'OpenApi\Annotations\OpenApi');
 echo $openapi->toJson();
 ```
 
-### Usage from [docker](https://docker.com)
-
-Generate the swagger documentation to a static json file.
-
-```
-docker run -v "$PWD":/app -it tico/swagger-php --help
-```
+## [Contributing](CONTRIBUTING.md)
 
 ## More on OpenApi & Swagger
 
@@ -113,43 +107,3 @@ docker run -v "$PWD":/app -it tico/swagger-php --help
 - [OpenApi Documentation](https://swagger.io/docs/)
 - [OpenApi Specification](http://swagger.io/specification/)
 - [Related projects](docs/related-projects.md)
-
-## Contributing
-
-Feel free to submit [Github Issues](https://github.com/zircote/swagger-php/issues)
-or pull requests.
-
-The documentation website is build from the [docs](docs/) folder with [vitepress](https://vitepress.vuejs.org).
-
-Make sure pull requests pass [PHPUnit](https://phpunit.de/)
-and [PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) (PSR-2) tests.
-
-### To run both unit tests and linting execute:
-```bash
-composer test
-```
-
-### To run static-analysis execute:
-```bash
-composer analyse
-```
-
-### Running unit tests only:
-```bash
-./bin/phpunit
-```
-
-### Regenerate reference markup docs
-```bash
-composer docs:gen
-```
-
-### Running linting only:
-```bash
-composer lint
-```
-
-### To make `php-cs-fixer` fix linting errors:
-```bash
-composer cs
-```

composer.json

@@ -82,7 +82,7 @@
         "testall": "Run all tests (test + testlegacy)",
         "analyse": "Run static analysis (phpstan/psalm)",
         "spectral": "Run spectral lint over all .yaml files in the Examples folder",
-        "docs:refgen": "Rebuild the annotations/attributes reference markup files",
+        "docs:gen": "Rebuild reference documentation",
         "docs:dev": "Run dev server for local development of gh-pages",
         "docs:build": "Re-build static gh-pages"
     },
@@ -103,11 +103,9 @@
             "export XDEBUG_MODE=off && psalm"
         ],
         "spectral": "for ff in `find Examples -name '*.yaml'`; do spectral lint $ff; done",
-        "docs:refgen": "php tools/refgen.php",
-        "docs:procgen": "php tools/procgen.php",
         "docs:gen": [
-            "@docs:refgen",
-            "@docs:procgen"
+            "@php tools/refgen.php",
+            "@php tools/procgen.php"
         ],
         "docs:dev": "cd docs && npm run dev",
         "docs:build": [

tools/src/Docs/ProcGenerator.php

@@ -71,13 +71,15 @@ public function getProcessorsDetails(): array
             if (!in_array($class, $defaultProcessors)) {
                 $rc = new \ReflectionClass($class);
 
-                $processors[] = [
-                    'class' => $rc->getName(),
-                    'name' => $rc->getShortName(),
-                    'default' => false,
-                    'options' => $this->getOptionsDetails($rc),
-                    'phpdoc' => $this->extractDocumentation($rc->getDocComment()),
-                ];
+                if (!$rc->isInterface()) {
+                    $processors[] = [
+                        'class' => $rc->getName(),
+                        'name' => $rc->getShortName(),
+                        'default' => false,
+                        'options' => $this->getOptionsDetails($rc),
+                        'phpdoc' => $this->extractDocumentation($rc->getDocComment()),
+                    ];
+                }
             }
         }