Add Contributing.md (#1412)
This commit is contained in:
Martin Rademacher
GitHub
parent
a060ea2494
commit
3f98e8fb2d
|
|
@ -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)
|
||||
54
README.md
54
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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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": [
|
||||
|
|
|
|||
|
|
@ -71,13 +71,15 @@ class ProcGenerator extends DocGenerator
|
|||
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()),
|
||||
];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue