Generate interactive Swagger documentation for your RESTful API using doctrine annotations.
- Compatible with the Swagger 2.0 specification.
- Exceptional error reporting (with hints, context)
- Extracts information from code & existing phpdoc annotations.
- Command-line interface available.
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 swagger
executable can be located by your system.
composer global require zircote/swagger-php
Add annotations to your php files.
/**
* @SWG\Info(title="My First API", version="0.1")
*/
/**
* @SWG\Get(
* path="/api/resource.json",
* @SWG\Response(response="200", description="An example resource")
* )
*/
See the Examples directory for more.
Generate always-up-to-date the swagger documentation dynamically.
<?php
require("vendor/autoload.php");
$swagger = \Swagger\scan('/path/to/project');
header('Content-Type: application/json');
echo $swagger;
Generate the swagger documentation to a static json file.
./vendor/bin/swagger --help
Generate the swagger annotation object from a json string, which makes it easier to manipulate swagger object programmatically.
<?php
use Swagger\Serializer;
$serializer = new Serializer();
$swagger = $serializer->deserialize($jsonString, 'Swagger\Annotations\Swagger');
echo $swagger;
- http://swagger.io/
- https://github.com/swagger-api/swagger-spec/
- http://bfanger.github.io/swagger-explained/
Feel free to submit Github Issues or pull requests.
The documentation website resides within the gh-pages
branch.
Make sure pull requests pass PHPUnit and PHP_CodeSniffer (PSR-2) tests.
Running tests can be done with this command in the root of the project:
./bin/phpunit
To run the phpcs tests on your local machine execute:
./bin/phpcs -p --extensions=php --standard=PSR2 --error-severity=1 --warning-severity=0 ./src ./tests