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.

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 (deprecated, removed in 8.0) (multiple values allowed)
  -r, --remove-processor=REMOVE-PROCESSOR  Remove an existing processor (deprecated, removed in 8.0) (multiple values allowed)
      --version=VERSION                    The OpenAPI version
      --plugin=PLUGIN                      Add this plugin class, built without settings (e.g. --plugin "Vendor\Package\Plugin") (multiple values allowed)
      --component-namer=COMPONENT-NAMER    Name components with this class, a built-in namer's class name or a FQCN (e.g. --component-namer QualifiedName)
  -m, --mode=MODE                          Set mode classic, hybrid or spec (deprecated, removed in 8.0 - leave it out for hybrid) [default: "hybrid"]
  -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 passed to the Builder constructor.

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

Augmenters are configured with the withAugmenters() hook:

php
$result = (new \OpenApi\Builder())
    ->addSource('/path/to/project')
    ->withAugmenters(function ($pipeline) {
        $pipeline->get(\OpenApi\Augmenter\OperationIds::class)->setHash(false);
    })
    ->build();

The settings each augmenter takes are listed in the Augmenter reference.

Instead of file paths, \ReflectionClass instances can also be passed directly:

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

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

echo $result->toYaml();

Configuring the Generator ​

In classic mode (setMode(Mode::CLASSIC)), the Builder runs the Generator. Custom analysers, processors and aliases are set on it with withGenerator().

Programming API

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