Generate interactive OpenAPI documentation for your RESTful API using PHP attributes (preferred) or
doctrine annotations (requires additional doctrine/annotations library).
See the documentation website for supported attributes and annotations.
Annotations are deprecated and may be removed in a future release of swagger-php.
- Compatible with the OpenAPI 3.0 and 3.1 specification.
- Extracts information from code and 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 8.2.
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.
If your code uses doctrine annotations you will need to install that library manually:
composer require doctrine/annotationsAdd annotations to your php files.
use OpenApi\Annotations as OA;
/**
* @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 = (new \OpenApi\Generator->generate(['/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 --helpGenerate 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();As of version 6, resolution of types is done using the TypeInfoTypeResolver class. It uses the symfony/type-info
library under the hood which improves handling of complext types.
If this is not desired, the LegacyTypeResolver can be used to preserve the old behaviour of version 5.
The LegacyTypeResolver is deprecated and will be removed in a future release.