Swagger-PHP

https://github.com/zircote/swagger-php
Admin
Swagger-PHP is a PHP library that generates OpenAPI documentation from annotations or attributes in...
Tokens:156,486
Snippets:1,289
Trust Score:9
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Full example of using the Generator class

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/generator.md

Shows a complete setup with a logger, custom processors, a Finder, and a context. It sets aliases, namespaces, analyser, and version before generating. Aliases and namespaces are optional and only needed for annotations.

```php
require('vendor/autoload.php');

$validate = true;
$logger = new \Psr\Log\NullLogger();
$processors = [/* my processors */];
$finder = \Symfony\Component\Finder\Finder::create()->files()->name('*.php')->in(__DIR__);

$context = new OpenApi\Context();

$openapi = (new \OpenApi\Generator($logger))
            ->setProcessorPipeline(new \OpenApi\Utils\Pipeline($processors))
            ->setAliases(['MY' => 'My\Annotations'])
            ->setNamespaces(['My\Annotations\'])
            ->setAnalyser(new \OpenApi\Analysers\ReflectionAnalyser([new OpenApi\Analysers\DocBlockAnnotationFactory(), new OpenApi\Analysers\AttributeAnnotationFactory()]))
            ->setVersion(\OpenApi\Annotations\OpenApi::VERSION_3_0_0)
            ->generate(['/path1/to/project', $finder], new \OpenApi\Analysis([], $context), $validate);
```

--------------------------------

### Install documentation dependencies

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/under-the-hood.md

Run this command in the docs directory to install the VitePress dependencies required for building the documentation.

```shell
cd docs
npm install
```

--------------------------------

### Explicit context example (PHP annotations)

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/augmentation.md

Shows the equivalent explicit annotations that produce the same result as the context-aware example. This demonstrates how to explicitly set the property name, description, and type.

```php
<<< @/snippets/guide/augmentation/explicit_context_at.php
```

```php
<<< @/snippets/guide/augmentation/explicit_context_an.php
```

```php
<<< @/snippets/guide/augmentation/explicit_context_spec.php
```

--------------------------------

### Install swagger-php per project with Composer

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/installation.md

Installs swagger-php as a dependency for the current project using Composer.

```shell
> composer require zircote/swagger-php
```

--------------------------------

### Custom augmenter examples: PipeInterface and #[Config] attribute

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/architecture.md

Two complete PHP class examples for creating custom augmenters. The first shows the required PipeInterface methods, including group() and __invoke(), with options for iterating schemas, walking attributes, or processing $refs. The second shows declaring a configurable parameter with the #[Config] attribute, which requires a matching setter method for CLI and Pipeline::configure().

```php
use OpenApi\Utils\PipeInterface;
use OpenApi\Specification;
use OpenApi\Spec as OA;

class CustomAugmenter implements PipeInterface
{
    public function group(): string|\BackedEnum
    {
        return \OpenApi\Augmenter\Group::Augment;
    }

    public function __invoke(mixed $payload): mixed
    {
        foreach ($payload->schemas as $schema) {
            // enrich schemas...
        }

        // or

        // the walker will walk all attributes (including nested) of the specification
        $payload->getWalker()->visit(OA\Property::class, function (OA\Property $property) {
            // ...
        });

        // or walk all attributes with $ref set
        $payload->getWalker()->eachRef(function () {
            // $attribute->ref = ...
        });

        return $payload;
    }
}
```

```php
use OpenApi\Utils\Config;
use OpenApi\Utils\PipeInterface;

class CustomAugmenter implements PipeInterface
{
    public function __construct(
        #[Config('Whether the custom rule is applied.')]
        protected bool $enabled = true,
    ) {
    }

    public function setEnabled(bool $enabled): static
    {
        $this->enabled = $enabled;

        return $this;
    }

    // ...
}
```

--------------------------------

### Install radebatz/type-info-extras for TypeInfoTypeResolver

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/installation.md

Installs the optional radebatz/type-info-extras package required for the TypeInfoTypeResolver on PHP 8.2 or higher. This also adds symfony/type-info as a dependency.

```shell
composer require radebatz/type-info-extras
```

--------------------------------

### Install doctrine/annotations for doctrine annotations

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/installation.md

Installs the doctrine/annotations library manually, required if your code uses doctrine annotations. As of version 4.8, this library is optional and no longer installed by default.

```shell
composer require doctrine/annotations
```

--------------------------------

### Install swagger-php globally with Composer

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/installation.md

Installs swagger-php globally using Composer's global argument. Remember to add the ~/.composer/vendor/bin directory to your PATH.

```shell
> composer global require zircote/swagger-php
```

--------------------------------

### Basic annotation usage with @OA\Info and @OA\Get

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/using-annotations.md

Complete example of using annotations in a class and method docblock. Shows @OA\Info and @OA\Get with a nested @OA\Response.

```php
<?php

use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My First API", version="0.1")
 */
class OpenApi {}

class MyController {

    /**
     * @OA\Get(
     *     path="/api/resource.json",
     *     @OA\Response(response="200", description="An example resource")
     * )
     */
    public function resource() {
        // ...
    }
}
```

--------------------------------

### Generate OpenAPI document from PHP

Source: https://github.com/zircote/swagger-php/blob/master/README.md

Generates always-up-to-date documentation from PHP. The example builds an OpenAPI document from a project path and outputs it as YAML.

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

```

--------------------------------

### Equivalent MediaType example

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/attributes.md

Shows the equivalent MediaType attribute usage for the same JSON response, using a schema reference.

```php
#[OA\MediaType(
    mediaType: 'application/json',
    schema: new OA\Schema(
        ref: '#/components/schemas/user'
    )
)
```

--------------------------------

### expandEnums.enumNames example output

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/processors.md

Example output of the expandEnums.enumNames configuration. Setting ->setEnumNames('enumNames') yields this YAML extension variable with backed enum names.

```yaml
x-enumNames:
  - NAME1
  - NAME2
```

--------------------------------

### Using $ref to reference schemas

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/cookbook.md

Shows the typical way to reference schemas using $ref with custom schema names. This is the baseline example that the following alternatives improve upon.

```php
#[OAT\Schema(schema: 'user')]
class User
{
}

#[OAT\Schema()]
class Book
{
    /**
     * @var User
     */
    #[OAT\Property(ref: '#/components/schemas/user')]
    public $author;
}
```

--------------------------------

### Define a GET operation with OA\Operation\Get

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/spec-attributes.md

Use the typed subclass OA\Operation\Get to define a GET operation on a path. The example shows a response with a schema reference to the Pet class and the resulting OpenAPI YAML output.

```php
#[OA\Operation\Get(path: '/pets/{id}', responses: [
    new OA\Response(response: 200, description: 'A pet', content: [
        new OA\MediaType(schema: new OA\Schema(ref: Pet::class)),
    ]),
])]
public function show(int $id) {}
```

```yaml
paths:
  /pets/{id}:
    get:
      operationId: show
      responses:
        '200':
          description: A pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
```

--------------------------------

### Context-aware augmentation example (PHP annotations)

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/augmentation.md

Shows how swagger-php augments a Product schema from minimal annotations. The docblock and type hints provide the property name, description, and type. The output is shown in the following YAML block.

```php
<<< @/snippets/guide/augmentation/context_awareness_at.php
```

```php
<<< @/snippets/guide/augmentation/context_awareness_an.php
```

```php
<<< @/snippets/guide/augmentation/context_awareness_spec.php
```

--------------------------------

### Set up callbacks manually with Attributes and Annotations

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/cookbook.md

Shows how to set up callbacks manually using both Attributes and Annotations. The callbacks are defined in the `callbacks` parameter of the `@OA\Get` annotation, with a dynamic URL from the request query and a request body for the subscription payload. The Annotations example also includes a `responses` definition for the callback.

```php
#[OA\Get(
    // ...
    callbacks: [
        'onChange' => [
            '{$request.query.callbackUrl}' => [
                'post' => [
                    'requestBody' => new OA\RequestBody(
                        description: 'subscription payload',
                        content: [
                            new OA\MediaType(
                                mediaType: 'application/json',
                                schema: new OA\Schema(
                                    properties: [
                                        new OA\Property(
                                            property: 'timestamp',
                                            type: 'string',
                                            format: 'date-time',
                                            description: 'time of change'
                                        ),
                                    ],
                                ),
                            ),
                        ],
                    ),
                ],
            ],
        ],
    ],
    // ...
)]
```

```php
/**
 * @OA\Get(
 *     ...
 *     callbacks={
 *         "onChange"={
 *              "{$request.query.callbackUrl}"={
 *                  "post": {
 *                      "requestBody": @OA\RequestBody(
 *                          description="subscription payload",
 *                          @OA\MediaType(mediaType="application/json", @OA\Schema(
 *                              @OA\Property(property="timestamp", type="string", format="date-time", description="time of change")
 *                          ))
 *                      )
 *                  },
 *                  "responses": {
 *                      "202": {
 *                          "description": "Your server implementation should return this HTTP status code if the data was received successfully"
 *                      }
 *                  }
 *              }
 *         }
 *     }
 *     ...
 * )
 */
```

--------------------------------

### JsonContent shorthand example

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/attributes.md

Shows how to use the JsonContent attribute to define a JSON response with a reference to a schema.

```php
#[OA\JsonContent(
    ref: '#/components/schemas/user'
)]
```

--------------------------------

### Configure augmenters with Builder::withAugmenters()

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/augmenters.md

Configure augmenters programmatically using Builder::withAugmenters() and Pipeline::get(). This example enables hashing for operation IDs and sets path filter tags to include /pets/ and /store/.

```php
(new Builder())
    ->withAugmenters(function ($pipeline) {
        $pipeline->get(Augmenter\OperationIds::class)->setHash(true);
        $pipeline->get(Augmenter\PathFilter::class)->setTags(['/pets/', '/store/']);
    });
```

--------------------------------

### Use OpenAPI attributes to define an API endpoint

Source: https://github.com/zircote/swagger-php/blob/master/README.md

Shows how to use OpenAPI attributes to add metadata to a PHP class and method. The example defines an API info and a GET endpoint with a response.

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

```

--------------------------------

### allOf restructuring example

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/inheritance.md

Shows the resulting YAML structure after the Refs augmenter moves properties into a dedicated allOf entry, creating a pure allOf composition with an anonymous schema of type object.

```yaml
User:
  allOf:
    - $ref: '#/components/schemas/BaseModel'
    - type: object
      properties:
        email:
          type: string
```

--------------------------------

### Resulting OpenAPI YAML from context-aware augmentation

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/augmentation.md

The YAML output produced by the context-aware example above. It shows the augmented Product schema with the name property description and type.

```yaml
openapi: 3.0.0
components:
  schemas:
    Product:
      properties:
        name:
          description: "The product name"
          type: string
      type: object
```

--------------------------------

### Basic example of using the Generator

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/generator.md

Minimal usage of the Generator to generate an OpenAPI spec from a path. The generate() method does not support CLI exclude and pattern options directly.

```php
require('"vendor/autoload.php');

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

--------------------------------

### Configure processors via command line with -c

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/processors.md

Use the -c option to set processor configuration from the command line. The option takes a name/value pair with the processor name (starting lowercase) and the option name separated by a dot. Use -D to list available processor names and options; unknown keys are reported as warnings.

```shell
> ./vendor/bin/openapi -c operationId.hash=true src
> ./vendor/bin/openapi -c pathFilter.tags[]=/pets/ -c pathFilter.tags[]=/store/ src
```

--------------------------------

### Basic OpenAPI Spec Attributes Example

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/spec-attributes.md

Minimal OpenAPI specification using spec attributes: defines the OpenAPI version, API info, and server URL.

```php
use OpenApi\Spec as OA;

#[OA\OpenApi(version: '3.1.0')]
#[OA\Info(title: 'My API', version: '1.0.0')]
#[OA\Server(url: 'https://api.example.com')]
class OpenApiSpec {}
```

--------------------------------

### Define Operations with Spec Attributes

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/spec-attributes.md

Controller with GET operations for listing and showing pets, including parameters and responses.

```php
use OpenApi\Spec as OA;

class PetController
{
    #[OA\Operation\Get(path: '/pets', operationId: 'listPets', tags: ['pets'])]
    #[OA\Response(
        response: 200,
        description: 'A list of pets',
        content: [new OA\MediaType(
            mediaType: 'application/json',
            schema: new OA\Schema(type: 'array', items: new OA\Schema(ref: Pet::class)),
        )],
    )]
    public function list() {}

    #[OA\Operation\Get(path: '/pets/{petId}', operationId: 'showPet', tags: ['pets'])]
    #[OA\Parameter(name: 'petId', in: 'path', required: true)]
    #[OA\Response(
        response: 200,
        description: 'A single pet',
        content: [new OA\MediaType(mediaType: 'application/json', schema: new OA\Schema(ref: Pet::class))],
    )]
    public function show(int $petId) {}
}
```

--------------------------------

### Virtual model include markers

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/cookbook.md

These are include markers for external example files. They are not actual code and are excluded from extraction.

```php
<<< @/snippets/guide/cookbook/virtual_model_at.php
```

```php
<<< @/snippets/guide/cookbook/virtual_model_an.php
```

```php
<<< @/snippets/guide/cookbook/virtual_model_spec.php
```

--------------------------------

### Deprecation marker example

Source: https://github.com/zircote/swagger-php/blob/master/ROADMAP.md

Shows the @deprecated marker format used to indicate the version that removes a feature. The marker names the version and provides a replacement hint.

```php
/** @deprecated since 6.11, removed in 8.0 - use ... instead */
```

--------------------------------

### Add a simple augmenter to the pipeline

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/extension-points.md

A minimal augmenter example: any callable that takes a Specification and returns it can be added to the pipeline. It does not need to implement an interface; without PipeInterface it lands in the default group.

```php
$pipeline->add(fn (Specification $spec) => $spec);
```

--------------------------------

### Using Generator::withContext() to migrate from deprecated static config

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/migrating-to-v4.md

Shows how to use the new Generator::withContext() method to run an Analyser within a Generator context, replacing the removed static configuration options. The example creates an analyser, adds an alias and namespace, then processes a file within the context.

```php
$analyser = createMyAnalyser();

$analysis = (new Generator())
    ->addAlias('fo', 'My\\Attribute\\Namespace')
    ->addNamespace('Other\\Annotations\\')
    ->withContext(function (Generator $generator, Analysis $analysis, Context $context) use ($analyser) {
        $analyser->setGenerator($generator);
        $analysis = $analyser->fromFile('my_code.php', $context);
        $analysis->process($generator->getProcessors());

        return $analysis;
    });
```

--------------------------------

### WRITE: use @OA\Contact annotation

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/using-annotations.md

This example is marked as WRITE. It uses the @OA\Contact annotation instead of an object literal, which adds validation and triggers warnings on misspelled properties.

```php
/**
 * @OA\Info(
 *   title="My first API",
 *   version="1.0.0",
 *   @OA\Contact(
 *     email="support@example.com"
 *   )
 * )
 */
```

--------------------------------

### Use -b to load composer autoloader

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/faq.md

Run the openapi command with the -b option to include the application's autoloader, which registers the classloader with PHP. This is needed when using a global installation of swagger-php.

```shell
openapi -b myapp/vendor/autoload.php myapp/src
```

--------------------------------

### Using #[OA\PathItem] with prefix and tags

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/spec-attributes.md

Shows how to use #[OA\PathItem] on a class to group operations with shared configuration. The prefix is composed via class inheritance, and tags are cloned to operations that don't declare their own. This example produces paths /api/v1/users/ and /api/v1/users/{id}, both tagged with 'Users'.

```php
use OpenApi\Spec as OA;

#[OA\PathItem(prefix: '/api/v1')]
class BaseController {}

#[OA\PathItem(prefix: '/users', tags: ['Users'])]
class UserController extends BaseController
{
    #[OA\Operation\Get(path: '/')]
    public function list() {}

    #[OA\Operation\Get(path: '/{id}')]
    public function show(int $id) {}
}
```

--------------------------------

### Define reusable components with #[OA\Components]

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/spec-attributes.md

Defines reusable Parameter and Header definitions inside an #[OA\Components] container. Use this for types that cannot stand alone as root attributes, such as Parameter, Header, Link, and Example.

```php
use OpenApi\Spec as OA;

#[OA\Components]
class SharedComponents
{
    #[OA\Parameter(parameter: 'page', name: 'page', in: 'query')]
    #[OA\Schema(type: 'integer', default: 1)]
    public int $page;

    #[OA\Parameter(parameter: 'per_page', name: 'per_page', in: 'query')]
    #[OA\Schema(type: 'integer', default: 20)]
    public int $perPage;

    #[OA\Header(header: 'X-Rate-Limit', description: 'Requests remaining')]
    #[OA\Schema(type: 'integer')]
    public string $rateLimit;
}
```

--------------------------------

### No requestBody on Get, Head, Options, Trace

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/spec-attributes.md

Shows that in spec mode, `OA\Operation\Get` (and `Head`, `Options`, `Trace`) do not accept a `requestBody` parameter, raising `Error: Unknown named parameter $requestBody`. The comment and second attribute show that `Post` (or `Put`, `Patch`, `Delete`) should be used for request bodies.

```php
// Works in classic mode; a PHP error in spec mode, because
// Operation\Get::__construct() has no $requestBody parameter:
#[OA\Operation\Get(path: '/pets', requestBody: new OA\RequestBody(...))]

// Use Post, Put, Patch, or Delete for request bodies:
#[OA\Operation\Post(path: '/pets', requestBody: new OA\RequestBody(...))]
```

--------------------------------

### Parameter Attribute

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/attributes.md

The Parameter attribute is used to define a parameter in an OpenAPI operation. It supports various properties to specify the parameter's schema, examples, serialization style, and behavior.

```APIDOC
## Parameter Attribute

### Description
Defines a parameter for an API operation, including its schema, examples, and serialization behavior.

### Properties

#### ref
- **Type**: string|class-string|object|null
- **Required**: no
- **Description**: The relative or absolute path to the endpoint. See [Reference Object](https://spec.openapis.org/oas/v3.1.1.html#reference-object).

#### schema
- **Type**: OpenApi\Attributes\Schema|null
- **Required**: no
- **Description**: The schema defining the type used for the parameter.

#### example
- **Type**: mixed|null
- **Required**: no
- **Description**: Example of the media type. The example should match the specified schema and encoding properties if present. The example object is mutually exclusive of the examples object. Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

#### examples
- **Type**: array<Examples>
- **Required**: no
- **Description**: Examples of the parameter. Each example should contain a value in the correct format as specified in the parameter encoding. The examples object is mutually exclusive of the example object. Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

#### content
- **Type**: array<MediaType>|JsonContent|XmlContent|Attachable|null
- **Required**: no
- **Description**: A map containing the representations for the parameter. The key is the media type and the value describes it. The map must only contain one entry.

#### style
- **Type**: string|null
- **Required**: no
- **Description**: Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

#### explode
- **Type**: bool|null
- **Required**: no
- **Description**: When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When style is form, the default value is true. For all other styles, the default value is false.

#### allowReserved
- **Type**: bool|null
- **Required**: no
- **Description**: Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.

#### spaceDelimited
- **Type**: array|null
- **Required**: no
- **Description**: Space separated array values. This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

#### pipeDelimited
- **Type**: array|null
- **Required**: no
- **Description**: Pipe separated array values. This option replaces collectionFormat equal to pipes from OpenAPI 2.0.
```

--------------------------------

### Declare reusable components with #[Components]

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/spec-attributes.md

Declares reusable components (Parameter, Header, Example) on a DTO class that is not a root. The Components attribute itself is not emitted; its children are promoted to the components section of the OpenAPI document.

```php
#[Components]
class SharedComponents {
    #[Parameter(parameter: 'tenant_id', name: 'tenant_id', in: 'path', schema: new Schema(type: 'string'))]
    public string $tenantId;

    #[Header(header: 'X-Rate-Limit', schema: new Schema(type: 'integer'))]
    public string $rateLimit;

    #[Example(example: 'dog', summary: 'A dog', value: ['name' => 'Fido'])]
    public string $dogExample;
}
```

--------------------------------

### Custom response class with attributes and annotations

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/cookbook.md

Defines a custom response class extending OA\Response to prefill response code and description. Works with both attributes and annotations; the attribute setup line can be omitted for annotations-only usage.

```php
use OpenApi\Attributes as OA;

/**
 * @Annotation
 */
#[\[Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
class BadRequest extends OA\Response
{
    public function __construct()
    {
        parent::__construct(response: 400, description: 'Bad request');
    }
}

class Controller
{

    #[OA\Get(path: '/foo', responses: [new BadRequest()])]
    public function get()
    {
    }

    #[OA\Post(path: '/foo')]
    #[BadRequest]
    public function post()
    {
    }

    /**
     * @OA\Delete(
     *     path="/foo",
     *     @BadRequest()
     * )
     */
    public function delete()
    {
    }
}
```

--------------------------------

### Show openapi CLI help and options

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/generating-openapi-documents.md

Use this command to display the full help for the openapi CLI, including all available options and their descriptions. This is useful for discovering available flags and their usage.

```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
```

--------------------------------

### Add sources one at a time or set all at once

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/builder.md

Shows how to add sources individually with addSource() or set them all at once with setSources(). Sources can be directory paths, file paths, SplFileInfo, Finder instances, or nested iterables.

```php
// Add sources one at a time
$builder->addSource('src/Controllers');
$builder->addSource(new \OpenApi\Utils\SourceFinder('src/', ['tests']));

// Or set all at once
$builder->setSources(['src/Controllers', 'src/Models']);
```

--------------------------------

### Show openapi CLI help

Source: https://github.com/zircote/swagger-php/blob/master/README.md

Displays help for the openapi command line interface. Use this to see available options for generating static yaml/json files.

```shell
./vendor/bin/openapi --help
```

--------------------------------

### Not nested attributes example

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/using-attributes.md

Shows attributes placed at the same level, with separate #[OA\Response] attributes. This is the not nested style.

```php
    #[OA\Get(path: '/api/users')]
    #[OA\Response(response: 200, description: 'OK')]
    #[OA\Response(response: 401, description: 'Not allowed')]
    public function users() { /* ... */ }
```

--------------------------------

### OpenAPI 3.1.0 const property example

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/cookbook.md

Shows how the `const` property is supported in OpenApi 3.1.0 for a schema property.

```yaml
components:
  schemas:
    Airport:
        properties:
          kind:
            type: string
            const: Airport
```

--------------------------------

### Generate OpenAPI documentation

Source: https://github.com/zircote/swagger-php/blob/master/docs/index.md

Run the openapi CLI on your source directory to generate an openapi.yaml file.

```shell
> ./vendor/bin/openapi src -o openapi.yaml
```

--------------------------------

### Basic Builder usage with addSource and build

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/builder.md

Creates a Builder, adds two source directories, builds the OpenAPI document, and prints it as YAML. The build() method returns a Result object that provides access to the generated document, scanned files, and collected warnings/errors.

```php
$result = (new \OpenApi\Builder())
    ->addSource('src/Controllers')
    ->addSource('src/Models')
    ->build();

echo $result->toYaml();
```

--------------------------------

### OpenAPI 3.0.0 enum serialization example

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/cookbook.md

Shows how the `const` property is serialized into a single value `enum` for OpenAPI 3.0.0.

```yaml
components:
  schemas:
    Airport:
        properties:
          kind:
            type: string
            enum:
              - Airport
```

--------------------------------

### Run static analysis with composer analyse

Source: https://github.com/zircote/swagger-php/blob/master/CONTRIBUTING.md

Runs static analysis.

```shell
composer analyse
```

--------------------------------

### DON'T WRITE: object literal for contact

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/using-annotations.md

This example is marked as DON'T WRITE. It uses an object literal for the contact property, which works but lacks validation.

```php
/**
 * @OA\Info(
 *   title="My first API",
 *   version="1.0.0",
 *   contact={
 *     "email": "support@example.com"
 *   }
 * )
 */
```

--------------------------------

### Using PathParameter attribute in a controller

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/migrating-to-v4.md

Example of using the PathParameter attribute in a controller method to avoid duplicating parameter details and automatically pick up typehints.

```php
class MyController
{
    #[OA\Get(path: '/products/{product_id}')]
    public function getProduct(
        #[OA\PathParameter] string $product_id)
    {
    }
}
```

--------------------------------

### CLI --bootstrap option for constants

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/using-annotations.md

When using the CLI, include the PHP file with constants using the --bootstrap option.

```shell
> openapi --bootstrap constants.php
```

--------------------------------

### Nested attributes example

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/using-attributes.md

Shows attributes nested inside a single #[OA\Get] attribute, with responses defined as new OA\Response objects. This is the nested style.

```php
    #[OA\Get(
        path: '/api/users',
        responses: [
            new OA\Response(response: 200, description: 'OK'),
            new OA\Response(response: 401, description: 'Not allowed'),
        ]
    )]
    public function users() { /* ... */ }
```

--------------------------------

### Minimal API with @OA\Info and @OA\Get (PHP annotations)

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/minimum-requirements.md

Shows the minimal annotations required for a single endpoint using PHP annotations. The endpoint must have a path and at least one response.

```php
<<< @/snippets/minimal_api_an.php
```

--------------------------------

### Bootstrap a PHP file with openapi CLI

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/generating-openapi-documents.md

Use this command to bootstrap a PHP file before processing it, which is useful when using swagger-php without proper autoloading. The -b option preloads the file so PHP's reflection code can inspect it.

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

--------------------------------

### Capture real openapi CLI output

Source: https://github.com/zircote/swagger-php/blob/master/docs/dev/writing-docs.md

Run the openapi CLI to capture its help output and a spec-mode generation command. Hand-writing the help block previously introduced errors such as a wrong --mode description and a non-existent --version default.

```shell
./bin/openapi -h            # capture this
./bin/openapi --mode spec -D src
```

--------------------------------

### Run tests with Composer

Source: https://github.com/zircote/swagger-php/blob/master/docs/dev/testing.md

Run the test suite with Composer. Use --filter to target a single class, and composer performance for perf tests, which are excluded from the default run.

```shell
composer test                            # the whole suite
composer test -- --filter CompilerTest   # a single class
composer performance                     # perf tests, excluded from the default run
```

--------------------------------

### Report unknown OpenAPI types

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/why-spec.md

Example of an error message generated by the spec pipeline when an invalid type like 'date' is used instead of 'string' with a 'date' format.

```text
Schema has unknown type "date", expecting one of string, number, integer, boolean, array,
object, null in App\Model\Invoice::$issued
```

--------------------------------

### Configure augmenters via CLI -c option

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/augmenters.md

Use the -c option to configure augmenters from the command line. The first command enables hashing for operation IDs, and the second filters paths to include only /pets/ and /store/. Both require the --mode spec flag and a source path.

```shell
> ./vendor/bin/openapi --mode spec -c operationIds.hash=true src
> ./vendor/bin/openapi --mode spec -c pathFilter.tags[]=/pets/ -c pathFilter.tags[]=/store/ src
```

--------------------------------

### Using x property in annotations

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/vendor-extensions.md

The x property accepts an array (map) and unfolds into 'x-' properties in the OpenAPI output. The example shows how to add custom properties to an annotation.

```php
<<< @/snippets/guide/vendor-extensions/custom_property_at.php
```

```php
<<< @/snippets/guide/vendor-extensions/custom_property_an.php
```

```php
<<< @/snippets/guide/vendor-extensions/custom_property_spec.php
```

--------------------------------

### Minimal API with @OA\Info and @OA\Get (PHP attributes)

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/minimum-requirements.md

Shows the minimal annotations required for a single endpoint using PHP attributes. The endpoint must have a path and at least one response.

```php
<<< @/snippets/minimal_api_at.php
```

--------------------------------

### Configure augmenters with withAugmenters()

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/builder.md

For spec and hybrid modes, configure the augmenter pipeline. The hook runs when called; repeated calls configure the same pipeline. The pipeline is grouped into three phases: resolve, reduce, augment.

```php
use OpenApi\Augmenter;

$builder->withAugmenters(function (\OpenApi\Utils\Pipeline $pipeline) {
    // Disable an augmenter
    $pipeline->get(Augmenter\Cleanup::class)?->setEnabled(false);

    // Configure operationId generation
    $pipeline->get(Augmenter\OperationIds::class)?->setHash(true);

    // Filter to specific paths/tags (regular expressions, with delimiters)
    $pipeline->get(Augmenter\PathFilter::class)
        ?->setPaths(['/^\/api\/v2/'])
        ->setTags(['/^(Users|Products)$/']);

    // Insert a custom augmenter
    $pipeline->insert(new CustomAugmenter(), Augmenter\Inheritance::class);

    // Remove an augmenter entirely
    $pipeline->remove(Augmenter\EnumDescriptions::class);
});
```

--------------------------------

### Apply security to an operation

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/spec-attributes.md

Applies a security requirement to an operation. The example uses the bearerAuth scheme defined earlier. Security can also be applied globally via the OpenApi attribute or via PathItem.

```php
#[OA\Operation\Get(path: '/pets', security: [
    new OA\Security\Requirement(scheme: 'bearerAuth'),
])]
public function list() {}
```

--------------------------------

### Use -b to autoload a standalone file

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/faq.md

For a standalone file that does not use namespaces or autoloading, use -b to load the file itself. The file (or its folder) must still be provided as the target.

```shell
openapi -b src/test.php src/test.php
```

--------------------------------

### Run unit tests with composer test

Source: https://github.com/zircote/swagger-php/blob/master/CONTRIBUTING.md

Runs the unit tests. The second command filters to a single test class, CompilerTest.

```shell
composer test
composer test -- --filter CompilerTest   # a single test class
```

--------------------------------

### Configure processors with Generator::setConfig()

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/processors.md

Configure processors programmatically using Generator::setConfig(). Keys can be the same as on the command line or broken down into nested arrays.

```php
(new Generator())
    ->setConfig([
        'operationId.hash' => true,
        'pathFilter' => [
            'tags' => [
                '/pets/',
                '/store/',
            ],
        ],
    ]);
```

--------------------------------

### Define security schemes with typed subclasses

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/spec-attributes.md

Defines security schemes using typed subclasses from OpenApi\Spec. The example shows HTTP bearer, API key, and OAuth2 authorization code flows with scopes.

```php
use OpenApi\Spec as OA;

#[OA\Security\Scheme\Http(securityScheme: 'bearerAuth', scheme: 'bearer')]
#[OA\Security\Scheme\ApiKey(securityScheme: 'apiKey', name: 'X-API-Key', in: 'header')]
#[OA\Security\Scheme\OAuth2(securityScheme: 'oauth2', flows: [
    new OA\Flow\AuthorizationCode(
        authorizationUrl: 'https://auth.example.com/authorize',
        tokenUrl: 'https://auth.example.com/token',
        scopes: ['read:pets' => 'Read pets', 'write:pets' => 'Write pets'],
    ),
])]
class OpenApiSpec {}
```

--------------------------------

### OA\MediaType\Xml shortcut for application/xml

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/spec-attributes.md

Shows the verbose OA\MediaType definition for application/xml and the equivalent shortened OA\MediaType\Xml shortcut. The shortcut sets mediaType to 'application/xml' by default and expands ref, type, items, properties, and required into a nested OA\Schema automatically; if schema is explicitly set, those custom properties are ignored.

```php
#[OA\Response(response: 200, content: [
    new OA\MediaType(mediaType: 'application/xml', schema: new OA\Schema(type: 'array', items: new OA\Schema(ref: Pet::class))),
])]
```

```php
#[OA\Response(response: 200, content: [new OA\MediaType\Xml(type: 'array', items: new OA\Schema(ref: Pet::class))])]
```

--------------------------------

### Implicit OA\Property for OA\Schema\Items

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/shortcuts.md

In the OpenApi\Spec namespace, OA\Schema subclasses like OA\Schema\Items also benefit from implicit OA\Property inference. This example shows a property with #[OA\Schema\Items(ref: Tag::class)] and no explicit #[OA\Property].

```php
// No explicit #[OA\Property] needed
#[OA\Schema\Items(ref: Tag::class)]
public array $tags;
```

--------------------------------

### Using SourceFinder for exclude and pattern options

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/generator.md

Shows how to use SourceFinder to pass exclude and pattern options to the Generator, since generate() does not support them directly.

```php
$exclude = ['tests'];
$pattern = '*.php';

$openapi = (new \OpenApi\Generator())->generate(new \OpenApi\Utils\SourceFinder(__DIR__, $exclude, $pattern));
```

--------------------------------

### Contribute attributes with withSpecification()

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/builder.md

Runs after assembly and before resolution, taking attributes the assembler did not build, with or without a reflector. Contributions are resolved, augmented, and compiled with everything else. Hooks accumulate: every one runs in registration order.

```php
$builder->withSpecification(function (\OpenApi\Specification $specification) {
    $specification->add(new \OpenApi\Spec\Operation\Get(path: '/users'));
});
```

--------------------------------

### Accessing Builder result formats

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/generating-openapi-documents.md

Shows the available methods on the Builder result object to retrieve the spec in different formats, list scanned files, and get validation warnings/errors. Use these methods after building to access the generated document.

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

--------------------------------

### Configure resolver with withResolver()

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/builder.md

Adds a custom resolver to the builder. The hook runs when called; repeated calls configure the same instance. Resolvers implement OpenApi\Contracts\ResolverInterface and receive the FQCN and the Assembler in use; the first to return true claims the FQCN.

```php
use OpenApi\Resolver;
use OpenApi\Utils\TypedList;

$builder->withResolver(function (Resolver $resolver) {
    $resolver->withResolvers(fn (TypedList $resolvers) => $resolvers
        ->add(new MyResolver()));
});
```

--------------------------------

### Shortcut OA\Property with OA\Schema in spec namespace

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/shortcuts.md

In the OpenApi\Spec namespace, class properties with an OA\Schema attribute do not need an explicit OA\Property. This shortcut example shows the implicit form. The actual code is not visible on this page; it is included via an external snippet file.

```php
<<< @/snippets/guide/shortcuts/optional_property_short_spec.php
```

--------------------------------

### Verbose OA\Property with OA\Schema in spec namespace

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/shortcuts.md

In the OpenApi\Spec namespace, class properties with an OA\Schema attribute do not need an explicit OA\Property. This verbose example shows the explicit form. The actual code is not visible on this page; it is included via an external snippet file.

```php
<<< @/snippets/guide/shortcuts/optional_property_verbose_spec.php
```

--------------------------------

### OA\Property::contained() slot map example

Source: https://github.com/zircote/swagger-php/blob/master/docs/dev/pipeline.md

Shows how a child attribute declares its nesting target via the `contained()` method. The slot name (`properties[]`) refers to a property on the target class (`Schema`), not on the declaring attribute. A `[]` suffix appends to a collection; a bare name assigns a scalar.

```php
// OA\Property
public function contained(): array
{
    return [Schema::class => 'properties[]'];   // `properties` lives on Schema
}
```

--------------------------------

### PathItem with shared path-level parameters

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/spec-attributes.md

Place on a controller class; the path is inferred from its operations. Parameters, summary, description and servers are emitted at path level in the OpenAPI output.

```php
#[PathItem(parameters: [new Parameter\Path(name: 'id', schema: new Schema(type: 'integer'))])]
class ProductController {
    #[Operation\Get(path: '/products/{id}')]
    public function get() {}
}
```

--------------------------------

### Using annotations with @OA\Info

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/migrating-to-v4.md

Shows the annotation syntax for defining the OpenAPI info block, including a license and an attachable. Requires the Doctrine annotations library if not using attributes.

```php

use OpenApi\Annotations as OA;

/**
 * @OA\Info(
 *   version="1.0.0",
 *   title="My API",
 *   @OA\License(name="MIT"),
 *   @OA\Attachable()
 * )
 */
class OpenApiSpec
{
}

```

--------------------------------

### Set builder mode to SPEC in PHP

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/modes.md

Set the builder mode in PHP. Use Mode::SPEC or the string 'spec' to select the spec mode.

```php
use OpenApi\Builder;
use OpenApi\Builder\Mode;

$builder->setMode(Mode::SPEC);
// or: $builder->setMode('spec');
```

--------------------------------

### Generate OpenAPI spec with CLI modes

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/modes.md

Run the CLI to generate an OpenAPI specification from source files. The first command uses the 'spec' mode, the second uses 'hybrid' mode; both write output to openapi.yaml.

```shell
./vendor/bin/openapi src/ --mode spec -o openapi.yaml
./vendor/bin/openapi src/ --mode hybrid -o openapi.yaml
```

--------------------------------

### Print resolved default config with ./bin/openapi --mode spec -D

Source: https://github.com/zircote/swagger-php/blob/master/docs/dev/docs-toolchain.md

Print the resolved default configuration for the OpenAPI tool. The paths argument is required even when using -D; omitting it results in an error. This command is used to verify that the documented config settings match the actual defaults.

```shell
./bin/openapi --mode spec -D src
```

--------------------------------

### Basic Builder usage

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/generating-openapi-documents.md

Use this snippet to generate an OpenAPI document from PHP source files using the Builder class. It requires the Composer autoloader and outputs YAML to the browser.

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

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

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

--------------------------------

### Using attributes with OA\Info

Source: https://github.com/zircote/swagger-php/blob/master/docs/guide/migrating-to-v4.md

Shows the attribute syntax for defining the OpenAPI info block, using named arguments and the attachables parameter. This is the recommended approach for PHP 8.1 and later.

```php

use OpenApi\Attributes as OA;

#[OA\Info(
    version: '1.0.0',
    title: 'My API',
    attachables: [new OA\Attachable()]
)]
#[OA\License(name: 'MIT')]
class OpenApiSpec
{
}

```

--------------------------------

### Set Builder to Spec mode with setMode

Source: https://github.com/zircote/swagger-php/blob/master/docs/reference/builder.md

Sets the Builder to Spec mode (beta). Runs the spec attributes pipeline end-to-end: Assembler → Resolver → Augmenters → Compiler. Uses attributes from the OpenApi\Spec namespace with typed DTOs and version-aware compilers.

```php
$builder->setMode(Mode::SPEC);
// or: $builder->setMode('spec');
```
Tokens:
Raw