Swagger-PHP

Appearance

Generating OpenAPI documents ​

Using the command line ​

swagger-php includes a command line tool ./vendor/bin/openapi. This can be used to generate OpenAPI documents.

shell
> ./vendor/bin/openapi app -o openapi.yaml

Output Format

By default, the output format is YAML. If a filename is given (via --output or -o) the tool will use the file extension to determine the format.

The --format option can be used to force a specific format.

To use spec mode from the CLI, pass --mode spec:

shell
> ./vendor/bin/openapi app --mode spec -o openapi.yaml

Bootstrap

The bootstrap option -b is useful when trying to use swagger-php without proper autoloading.

For example, you might want to evaluate the library using a single file with just a few annotations. In this case telling swagger-php to bootstrap (preload) the file prior to processing it will ensure PHP's reflection code will be able to inspect your code.

shell
> ./vendor/bin/openapi -b my_file.php my_file.php

For a list of all available options use the -h option:

shell
> ./vendor/bin/openapi -h

Description:
  Generate OpenAPI documentation

Usage:
  openapi [options] [--] <paths>...

Arguments:
  paths                                    Source path(s) to scan

Options:
  -c, --config=CONFIG                      Generator/Augmenter config; keys differ per mode, see -D (e.g. -c operationId.hash=false) (multiple values allowed)
  -D, --defaults                           Show default config
  -o, --output=OUTPUT                      Path to store the generated documentation (e.g. -o openapi.yaml)
  -f, --format=FORMAT                      Force yaml or json [default: "auto"]
  -e, --exclude=EXCLUDE                    Exclude path(s) (e.g. -e vendor -e library/Zend) (multiple values allowed)
  -n, --pattern=PATTERN                    Pattern of files to scan (e.g. -n "/\.(phps|php)$/") [default: "*.php"]
  -b, --bootstrap=BOOTSTRAP                Bootstrap php file(s) for defining constants, etc. (e.g. -b config/constants.php) (multiple values allowed)
  -a, --add-processor=ADD-PROCESSOR        Register an additional processor (multiple values allowed)
  -r, --remove-processor=REMOVE-PROCESSOR  Remove an existing processor (multiple values allowed)
      --version=VERSION                    The OpenAPI version
  -m, --mode=MODE                          Set mode classic, hybrid or spec [default: "classic"]
  -d, --debug                              Show additional error information
  -h, --help                               Display help for the given command. When no command is given display help for the list command
      --silent                             Do not output any message
  -q, --quiet                              Only errors are displayed. All other output is suppressed
      --ansi|--no-ansi                     Force (or disable --no-ansi) ANSI output
  -v|vv|vvv, --verbose                     Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Using PHP ​

Depending on your use case, PHP code can also be used to generate OpenAPI documents in a more dynamic way.

Using the Builder ​

The Builder class is the recommended entry point for generating OpenAPI documents from PHP code.

php
<?php
require('vendor/autoload.php');

$result = (new \OpenApi\Builder())
    ->addSource('/path/to/project')
    ->build();

header('Content-Type: application/x-yaml');
echo $result->toYaml();

The result object provides access to the generated spec in multiple formats, the list of scanned files, and whether the build reported errors. The messages themselves go to the logger set with setLogger().

php
$result->toYaml();        // YAML string
$result->toJson();        // JSON string
$result->toArray();       // PHP array
$result->files();         // list of scanned files
$result->isValid();       // true if spec was generated and no errors were reported
$result->specification(); // the final `Specification` instance

For advanced Generator configuration (custom analysers, processors, aliases, etc.), use the withGenerator() hook:

php
$result = (new \OpenApi\Builder())
    ->addSource('/path/to/project')
    ->setVersion('3.1.0')
    ->withGenerator(function (\OpenApi\Generator $generator) {
        $generator->setConfig(['operationId.hash' => false]);
        $generator->withProcessorPipeline(function ($pipeline) {
            $pipeline->add(new MyCustomProcessor());
        });
    })
    ->build();

The keys setConfig() takes are listed per processor in the Processor reference.

Using spec mode ​

To use the new spec attributes pipeline (beta), set the mode to spec:

php
<?php
require('vendor/autoload.php');

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

header('Content-Type: application/x-yaml');
echo $result->toYaml();

Spec mode uses attributes from the OpenApi\Spec namespace. See Using Spec Attributes for details on the attribute API and Processing Modes for a comparison of all modes.

In spec and hybrid mode, you can also pass \ReflectionClass instances directly instead of file paths:

php
<?php
require('vendor/autoload.php');

$result = (new \OpenApi\Builder())
    ->setMode(\OpenApi\Builder\Mode::SPEC)
    ->addSource([
        new \ReflectionClass(App\Controllers\PetController::class),
        new \ReflectionClass(App\Models\Pet::class),
    ])
    ->build();

echo $result->toYaml();

Using the Generator directly ​

The Generator class can also be used directly (classic mode only):

php
<?php
require('vendor/autoload.php');

$openapi = (new \OpenApi\Generator())->generate(['/path/to/project']);

header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

Programming API

Details about the swagger-php API can be found in the reference.