Augmentation

One benefit of using swagger-php is that the library will use a number of strategies to augment your attributes and annotations.

This includes things like:

• the name of properties
• the description of elements
• the data type of properties

Based on the context of the attribute or annotation swagger-php will look at (in order of priority):

• the attribute or annotation itself
• the docblock (if any)
• PHP native type hints (if any)

Example

<?php

namespace Openapi\Snippets\Augmentation\Aware;

use OpenApi\Spec as OA;

#[OA\Schema]
class Product
{
    /**
     * The product name,.
     * @var string
     */
    #[OA\Property]
    public $name;
}

<?php

namespace Openapi\Snippets\Augmentation\Aware;

use OpenApi\Attributes as OA;

#[OA\Schema]
class Product
{
    /**
     * The product name,.
     * @var string
     */
    #[OA\Property]
    public $name;
}

<?php

namespace Openapi\Snippets\Augmentation\Aware;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema
 */
class Product
{
    /**
     * The product name,.
     * @var string
     * @OA\Property
     */
    public $name;
}

Results in

openapi: 3.1.0
components:
  schemas:
    Product:
      properties:
        name:
          description: "The product name"
          type: string
      type: object

As if you'd written

<?php

namespace Openapi\Snippets\Augmentation\Explicit;

use OpenApi\Spec as OA;

#[OA\Schema]
class Product
{
    /**
     * The product name.
     */
    #[OA\Property(property: 'name')]
    #[OA\Schema(
        type: 'string',
        description: 'The product name'
    )]
    public string $name;
}

<?php

namespace Openapi\Snippets\Augmentation\Explicit;

use OpenApi\Attributes as OA;

#[OA\Schema]
class Product
{
    /**
     * The product name.
     */
    #[OA\Property(
        property: 'name',
        type: 'string',
        description: 'The product name'
    )]
    public string $name;
}

<?php

namespace Openapi\Snippets\Augmentation\Explicit;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema
 */
class Product
{
    /**
     * The product name.
     * @var string
     *
     * @OA\Property(
     *     property="name",
     *     type="string",
     *     description="The product name"
     * )
     */
    public $name;
}

Data types

In particular, the following schema elements may be augmented:

• nullable
• items
• ref
• type
• format
• minimum / maximum
• const
• enum
• required
• default

Data types that are not recognized and cannot be resolved to a class-like name (class, interface, enum, etc.) will be ignored.

A class implementing DateTimeInterface, such as DateTimeImmutable or a subclass of it, is a string with format date-time.

Most of these schema elements will be resolved in isolation. For example, nullable may be enforced by the attribute or annotation while the actual data type may be resolved from the docblock (or type-hint).

Which source wins

For each element, the first source that sets it wins:

Element	Sources, in order
type	the attribute (type, oneOf, allOf or anyOf), the docblock, the type-hint
format, minimum, maximum, items	the attribute, then the type the docblock or type-hint gives, unless the attribute sets type
nullable	the attribute, then true if either the docblock or the type-hint is nullable, unless the attribute sets type
ref	the attribute, then a class type, if that class is a schema component

The docblock replaces the type-hint. It does not refine it: @var string on public int $id documents a string. A docblock type that cannot be parsed is ignored, and the type-hint is used.

The docblock tag read depends on the element:

• a property: @var
• a promoted constructor property: the constructor's @param
• a method: @return

Property examples

Mode difference

In the spec pipeline, a property's @example text is decoded as JSON when its value matches the schema's type. For example, @example false on a boolean property produces the boolean false. String schemas, unions containing string, and untyped schemas keep the text. Invalid JSON and values of a different type also keep the text. An explicit schema example or examples, including an empty list, takes precedence over the docblock. Property-backed parameters and headers follow these example rules. Headers need an explicit schema type for the example to be decoded, since their schema type is not inferred from the property.

Required properties and defaults

An object schema's required list and its properties' default come from the PHP declarations:

• a property is required when its PHP type is not nullable and it has no default. A property with no PHP type is never added.
• a property with a default gives that default, where it is a scalar, an enum case or an array of them. An enum case gives a backed case's value or a unit case's name, as the enum's schema lists them. null is not taken, and neither is a value the schema's type does not admit.

A parameter follows the same required rule, except that a path parameter is always required: left unset, required becomes true whatever its PHP type or default, and an explicit required: false gets a warning. A promoted constructor property counts by its parameter's default. An explicit required list on the schema is kept as written, and so is an explicit default on the property, default: null included.

#[OA\Schema]
class Pet
{
    #[OA\Property] public int $id;                 // required
    #[OA\Property] public ?string $nickname;       // not required: nullable
    #[OA\Property] public string $status = 'new';  // not required, default: new
}

Mode difference

Only spec attributes are read. Classic attributes and docblock annotations add neither, in classic or in hybrid, and a classic parameter stays required by its type alone, whatever its default. A path parameter is the exception: in hybrid it is required too.

Summary and description

summary and description of certain attribute types (OA\Operation, OA\Property, OA\Parameter, OA\Header and OA\Schema) may be augmented by extracting the summary and description of the docblock (if any).

Mode difference

In the spec pipeline, parameters and headers carrying a property's reflector get their description, @example and deprecation from its docblock. Promoted constructor parameters also use the property's docblock. Property-backed nested schemas use the docblock of the property they describe. Explicit values take precedence; description: null suppresses inference.

References

OpenApi specs support references to allow reuse of elements and reduce duplication. One of the most common use cases is to set the type or ref property of a schema to a class name. The only requirement is that the class is annotated with OA\Schema itself.

Tags

Tags are an OpenApi concept and may be added to your spec with OA\Tag. For convenience, however, it is also possible to create tags by just adding them to your HTTP operations (Get, Post, etc.). All tags used that are not explicitly defined with OA\Tag will be added to the spec.