Swagger-PHP - Generate interactive documentation for your RESTful API using phpdoc annotations

2.0.11 2017-08-16 08:32 UTC


Build Status Total Downloads License


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 Getting started guide and Examples directory for more examples.

Usage from php

Generate always-up-to-date documentation.

$swagger = \Swagger\scan('/path/to/project');
header('Content-Type: application/json');
echo $swagger;

Usage from the Command Line Interface

Generate the swagger documentation to a static json file.

./vendor/bin/swagger --help

Usage from the Deserializer

Generate the swagger annotation object from a json string, which makes it easier to manipulate swagger object programmatically.


use Swagger\Serializer;

$serializer = new Serializer();
$swagger = $serializer->deserialize($jsonString, 'Swagger\Annotations\Swagger');
echo $swagger;

Usage from docker

Generate the swagger documentation to a static json file.

docker run -v "$PWD":/app -it tico/swagger-php --help

More on Swagger


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:


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

To run both unittests and linting execute:

composer test

Bitdeli Badge