Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations.

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.

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

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.

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 Migration guide.

The openapi command line interface can be used to generate the documentation to a static yaml/json file.

./vendor/bin/openapi --help

Starting 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();

Generate the swagger documentation to a static json file.

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

• https://swagger.io
• https://www.openapis.org
• OpenApi Documentation
• OpenApi Specification
• Related projects

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.

composer test

./bin/phpunit

composer lint

composer cs