The Zircote/Swagger-PHP is a powerful composer package designed for automatic generation of interactive OpenAPI documentation for your RESTful APIs by using PHPDoc annotations. The tool is compatible with OpenAPI 3.0 and 3.1 specifications and is capable of extracting information from code and existing PHPDoc annotations. Zircote/Swagger-PHP is known for its exceptional error reporting and as of PHP 8.1, all its annotations are available as PHP attributes.
To take advantage of Zircote/Swagger-PHP in your project, you can install it with Composer with the command composer require zircote/swagger-php. You can then add the necessary annotations to your PHP files, defining the information that you want to include in your API documentation. For instance:
/**
* @OA\Info(title="My First API", version="0.1")
*/
/**
* @OA\Get(
* path="/api/resource.json",
* @OA\Response(response="200", description="An example resource")
* )
*/
To generate and display your documentation, you just need to call the appropriate methods as in the below example:
<?php
require("vendor/autoload.php");
$openapi = \OpenApi\Generator::scan(['/path/to/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();
You may set the version of your OpenAPI documentation using the Generator::setVersion() method. Also, you can utilize the command-line interface that's offered by Zircote/Swagger-PHP to generate the documentation into a static file.
The full details of how to use the Zircote/Swagger-PHP package, including a comprehensive list of supported annotations, are available on the official documentation website. The website features a getting started guide, a guide to using the annotations, information on how to use the Generator class and much more. To dive deeper into real world examples, you can browse the Examples directory in the package's repository on GitHub.
