006bd7fc75
* Use raw phpunit command instead of action * Remove invalid/redundant args from security checker |
||
|---|---|---|
| .github/workflows | ||
| Examples | ||
| bin | ||
| docs | ||
| src | ||
| tests | ||
| .gitignore | ||
| .php_cs.dist | ||
| Changelog.md | ||
| LICENSE-2.0.txt | ||
| README.md | ||
| composer.json | ||
| phpunit.xml.dist | ||
| psalm.xml | ||
README.md
swagger-php
Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations.
Features
- Compatible with the OpenAPI 3.0 specification.
- Extracts information from code & existing phpdoc annotations.
- Command-line interface available.
- Documentation site with a getting started guide.
- Exceptional error reporting (with hints, context)
Installation (with Composer)
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.
composer global require zircote/swagger-php
Usage
Add annotations to your php files.
/**
* @OA\Info(title="My First API", version="0.1")
*/
/**
* @OA\Get(
* path="/api/resource.json",
* @OA\Response(response="200", description="An example resource")
* )
*/
Visit the Documentation website for the Getting started guide or look at the Examples directory for more examples.
Usage from php
Generate always-up-to-date documentation.
<?php
require("vendor/autoload.php");
$openapi = \OpenApi\scan('/path/to/project');
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();
Usage from the Command Line Interface
Generate the documentation to a static json file.
./vendor/bin/openapi --help
Usage from the Deserializer
Generate the OpenApi annotation object from a json string, which makes it easier to manipulate objects programmatically.
<?php
use OpenApi\Serializer;
$serializer = new Serializer();
$openapi = $serializer->deserialize($jsonString, 'OpenApi\Annotations\OpenApi');
echo $openapi->toJson();
Usage from docker
Generate the swagger documentation to a static json file.
docker run -v "$PWD":/app -it tico/swagger-php --help
More on OpenApi & Swagger
- https://swagger.io
- https://www.openapis.org
- OpenApi Documentation
- OpenApi Specification
- Related projects
Contributing
Feel free to submit Github Issues or pull requests.
The documentation website is build from the docs folder with vuepress.
Make sure pull requests pass PHPUnit and PHP-CS-Fixer (PSR-2) tests.
To run both unit tests and linting execute:
composer test
Running unit tests only:
./bin/phpunit
Running linting only:
composer lint
To make php-cs-fixer fix linting errors:
composer cs