swagger-php Documentation

Technical Documentation: zircote/swagger-php

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

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

• 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.
• Error reporting (with hints, context).
• 🧪 Spec attributes (beta): attributes that can also be built by hand and compiled without scanning, and a pipeline that reports when an attribute is wrong. See Why spec attributes?.

OpenAPI version support Copy Chapter

swagger-php can generate specs for OpenAPI 3.0.0, OpenAPI 3.1.0 and OpenAPI 3.2.0.
Classic mode defaults to 3.0.0, spec and hybrid mode to 3.1.0.

The command line option --version selects a different version; programmatically, use
Builder::setVersion().

Requirements Copy Chapter

swagger-php requires at least PHP 8.2.

Installation (with [Composer](https://getcomposer.org)) Copy Chapter

composer require zircote/swagger-php

For cli usage from anywhere, install swagger-php globally and add Composer's global binary directory
(composer global config bin-dir --absolute) to your PATH, so the openapi executable can be located by
your system.

composer global require zircote/swagger-php

doctrine/annotations Copy Section

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:

composer require doctrine/annotations

Usage Copy Chapter

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

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) Copy Section

Available since 6.5.0

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

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() {}
}

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

Hybrid mode works with your existing OpenApi\Attributes code, with no changes needed. It runs the classic scanner
but uses the new augmenter pipeline and version-aware compilers, which are easier to extend.
Switching to hybrid is also the easiest way to help test the new pipeline:

$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 Copy Section

Generate always-up-to-date documentation.

<?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 Copy Section

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

./vendor/bin/openapi --help

Automatic type resolution Copy Chapter

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 complex types.

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

For example, the following two examples are now equivalent:

class MyClass
{
    #[OAT\Property(items: new OAT\Items(oneOf: [
        new OAT\Schema(type: SchemaOne::class),
        new OAT\Schema(type: SchemaTwo::class),
    ]))]
    public array $values;
}

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](CONTRIBUTING.md) Copy Chapter

More on OpenApi & Swagger Copy Chapter

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

--- METRICS ---

• Files Extracted: 1
• Estimated Token Budget: ~1508 tokens
• Canonical Reference: https://codewiki.google/github.com/zircote/swagger-php