Augmentation

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

This includes things like:

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

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

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

Example

<?php

use OpenApi\Attributes as OA;

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

<?php

use OpenApi\Annotations as OA;

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

Results in

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

As if you'd written

<?php

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

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

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

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

Summary and description

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

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 name must be annotated as a OA\Schema itself.

Tags

Tags are an OpenApi concept and may be added to your spec via th Tag annotation. 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 a Tag annotation will be added to the spec.