Generate interactive OpenAPI documentation for your RESTful API using
doctrine annotations (optional as of version 4.8; if required the doctrine/annotations library must be installed in addition to swagger.php).
or PHP attributes.
For a full list of supported annotations, please have look at the OpenApi\Annotations namespace or the documentation website.
- Compatible with the OpenAPI 3.0 and 3.1 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)
- As of PHP 8.1 all annotations are also available as PHP attributes
swagger-php allows to generate specs either for OpenAPI 3.0.0 or OpenAPI 3.1.0.
By default the spec will be in version 3.0.0. The command line option --version may be used to change this
to 3.1.0.
Programmatically, the method Generator::setVersion() can be used to change the version.
swagger-php requires at least PHP 7.2 for annotations and PHP 8.1 for using attributes.
Installation (with Composer)
composer require zircote/swagger-phpFor 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-phpAs of version 4.8 the doctrine annotations library is optional and no longer installed by default.
To use PHPDoc annotations this needs to be installed on top of swagger-php:
composer require doctrine/annotationsIf your code uses PHPDoc annotations you will need to install this as well:
composer require doctrine/annotationsAdd 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.
Generate always-up-to-date documentation.
<?php
require("vendor/autoload.php");
$openapi = \OpenApi\Generator::scan(['/path/to/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();Documentation of how to use the Generator class can be found in the Generator reference.
The openapi command line interface can be used to generate the documentation to a static yaml/json file.
./vendor/bin/openapi --helpStarting with version 4 the default analyser used on the command line is the new ReflectionAnalyser.
Using the --legacy flag (-l) the legacy TokenAnalyser can still be used.
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();