ContextQMD
Back to Swagger Php

swagger-php

README.md

6.5.06.2 KB
Original Source

swagger-php

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.

Features

  • Compatible with the OpenAPI 3.0, 3.1 and 3.2 specification.
  • Extracts information from code and existing phpdoc comments.
  • Can be used programmatically or via command-line tool.
  • Documentation site with a getting started guide.
  • Error reporting (with hints, context).
  • All metadata is configured via PHP attributes.
  • 🧪 Spec attributes pipeline (beta) — a new processing mode with typed DTOs, grouped augmenters, and version-aware compilers.

OpenAPI version support

swagger-php allows to generate specs either for OpenAPI 3.0.0, OpenAPI 3.1.0 and OpenAPI 3.2.0. By default, the spec will be in version 3.0.0. The command line option --version may be used to change to any other supported version.

Programmatically, the method Generator::setVersion() can be used to change the version.

Requirements

swagger-php requires at least PHP 8.2.

Installation (with Composer)

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

shell
composer global require zircote/swagger-php

doctrine/annotations

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

shell
composer require doctrine/annotations

Usage

Use OpenAPI attributes to add metadata to your classes, methods and other structural PHP elements.

php

use OpenApi\Attributes as OAT;

#[OAT\Info(title: 'My First API', version: '0.1')]
class MyApi
{
    #[OAT\Get(path: '/api/resource.json')]
    #[OAT\Response(response: '200', description: 'An example resource')]
    public function getResource()
    {
        // ...
    }
}

Visit the Documentation website for the Getting started guide or look at the examples directory for more examples.

🧪 Spec Attributes (Beta)

Available since 6.5.0

A new processing mode using typed attributes from the OpenApi\Spec namespace:

php
use OpenApi\Spec as OA;

#[OA\OpenApi(version: '3.1.0')]
#[OA\Info(title: 'My API', version: '1.0')]
class MyApi
{
    #[OA\Operation\Get(path: '/api/resource')]
    #[OA\Response(response: 200, description: 'An example resource')]
    public function getResource() {}
}
php
$result = (new \OpenApi\Builder())
    ->setMode(\OpenApi\Builder\Mode::SPEC)
    ->addSource('src/')
    ->build();

Hybrid mode works with your existing OpenApi\Attributes code — no changes needed. It runs the classic scanner but uses the new augmenter pipeline and version-aware compilers, which is faster and easier to extend. If you'd like to help test the new pipeline, switching to hybrid is the easiest way:

php
$result = (new \OpenApi\Builder())
    ->setMode(\OpenApi\Builder\Mode::HYBRID)
    ->addSource('src/')
    ->build();

Or from the CLI: ./vendor/bin/openapi src/ --mode hybrid

See the Spec Attributes guide and Processing Modes for full documentation.

Usage from PHP

Generate always-up-to-date documentation.

php
<?php
require("vendor/autoload.php");
$result = (new \OpenApi\Builder())
    ->addSource(['/path/to/project'])
    ->build();
header('Content-Type: application/x-yaml');
echo $result->toYaml();

Details on how to generate OpenApi specifications can be found in the generate 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.

shell
./vendor/bin/openapi --help

Automatic type resolution

As of version 6, resolving of types is done using the TypeInfoTypeResolver class. It uses the symfony/type-info library under the hood which allows handling of complext types.

With this change, swagger-php supports all available native type-hints and also complext generic type-hints via phpdoc blocks. This simplifies the definition of schemas.

For example, the following two examples are now equivalent:

php
class MyClass
{
    #[OAT\Property(items: new OAT\Items(oneOf: [
        new OAT\Schema(type: SchemaOne::class),
        new OAT\Schema(type: SchemaTwo::class),
    ]))]
    public array $values;
}
php
class MyClass
{
    /**
     * @var list<SchemaOne|SchemaTwo>
     */
    public array $values;
}

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.

Contributing

More on OpenApi & Swagger