Go to file
2024-07-10 14:06:32 +12:00
.github Bump ramsey/composer-install from 2 to 3 (#1551) 2024-03-04 17:41:38 +13:00
bin Replace current processor array with a pipeline class (#1585) 2024-06-05 15:52:28 +12:00
docs Add processor config section to reference (#1618) 2024-07-02 16:16:30 +12:00
Examples Strip duplicate tags in AugmentTags (#1622) 2024-07-04 19:53:11 +12:00
src Remove unused tags (#1625) 2024-07-10 14:06:32 +12:00
tests Remove unused tags (#1625) 2024-07-10 14:06:32 +12:00
tools Add processor config section to reference (#1618) 2024-07-02 16:16:30 +12:00
.editorconfig Dev tools (#1243) 2022-05-20 16:17:19 +12:00
.gitattributes export-ignore docs and Changelog.md (#1277) 2022-06-28 16:17:40 +12:00
.gitignore Docs codeblock (#1533) 2024-01-19 10:51:32 +13:00
.php-cs-fixer.dist.php Update jsonSerialize return (#1575) 2024-05-01 10:01:17 +12:00
.spectral.yaml Improve example specs (#990) 2021-10-08 14:11:42 +13:00
Changelog.md Document the changelog on the github releases page 2018-05-22 11:00:17 +02:00
composer.json Revert "Re-implement TokenScanner using nikic/php-parser (#1597)" (#1599) 2024-06-04 17:24:03 +12:00
CONTRIBUTING.md Add Contributing.md (#1412) 2023-02-13 14:40:06 +13:00
LICENSE Rename license file to be in line with what GH expects (#1188) 2022-04-06 15:38:04 +12:00
NOTICE Adding copyright notice (#1347) 2022-12-04 12:29:07 +13:00
phpstan-baseline.neon Revert "Re-implement TokenScanner using nikic/php-parser (#1597)" (#1599) 2024-06-04 17:24:03 +12:00
phpstan.neon Explicitly set the PHP version (#1284) 2022-07-06 12:51:10 +12:00
phpunit.xml.dist Github action CI migration (#886) 2021-01-06 08:46:26 +13:00
psalm-baseline.xml Add Psalm to analysis chain (#1223) 2022-05-04 11:32:59 +12:00
psalm.xml Address PHP 8.2. warnings and static analysis (#1263) 2022-06-20 11:53:03 +12:00
README.md Add more notes about doctrine/annotations being optional as of version 4.8 (#1516) 2023-12-11 21:35:08 +13:00

Build Status Total Downloads License


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

OpenAPI version support

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-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


As 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/annotations

If your code uses PHPDoc annotations you will need to install this as well:

composer require doctrine/annotations


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.

Usage from php

Generate always-up-to-date documentation.

$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.

Usage from the Command Line Interface

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.

Usage from the Deserializer

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


use OpenApi\Serializer;

$serializer = new Serializer();
$openapi = $serializer->deserialize($jsonString, 'OpenApi\Annotations\OpenApi');
echo $openapi->toJson();


More on OpenApi & Swagger