Shortcuts

To help keeping your annotations simple, there are a few shortcut annotations available in swagger-php. Typically, these save you from creating boilerplate nested OA\Schema annotations.

OA\MediaType

OA\MediaType is used to describe the content of a response.

<?php

namespace Openapi\Snippets\Shortcuts\MediaType;

use OpenApi\Attributes as OA;

class Controller
{
    #[OA\Response(
        response: 200,
        description: 'successful operation',
        content: new OA\MediaType(
            mediaType: 'application/json',
            schema: new OA\Schema(ref: '#/components/schemas/User'),
        ),
    )]
    public function endpoint()
    {
    }
}

<?php

namespace Openapi\Snippets\Shortcuts\MediaType;

use OpenApi\Annotations as OA;

class Controller
{
    /**
     * @OA\Response(
     *     response=200,
     *     description="successful operation",
     *     @OA\MediaType(
     *         mediaType="application/json",
     *         @OA\Schema(ref="#/components/schemas/User"),
     *     )
     * ),
     */
    public function endpoint()
    {
    }
}

<?php

namespace Openapi\Snippets\Shortcuts\MediaType;

use OpenApi\Spec as OA;

class Controller
{
    #[OA\Response(
        response: 200,
        description: 'successful operation',
        content: [new OA\MediaType(
            mediaType: 'application/json',
            schema: new OA\Schema(ref: '#/components/schemas/User'),
        )],
    )]
    public function endpoint()
    {
    }
}

For JSON and Xml content, swagger-php provides shortcut annotations to avoid having to specify the mediaType over and over again.

Example using OA\JsonContent

<?php

namespace Openapi\Snippets\Shortcuts\ResponseJson;

use OpenApi\Attributes as OA;

class Controller
{
    #[OA\Response(
        response: 200,
        description: 'successful operation',
        content: new OA\JsonContent(
            ref: '#/components/schemas/User',
        ),
    )]
    public function endpoint()
    {
    }
}

<?php

namespace Openapi\Snippets\Shortcuts\ResponseJson;

use OpenApi\Annotations as OA;

class Controller
{
    /**
     * @OA\Response(
     *     response=200,
     *     description="successful operation",
     *     @OA\JsonContent(ref="#/components/schemas/User"),
     * )
     */
    public function endpoint()
    {
    }
}

<?php

namespace Openapi\Snippets\Shortcuts\ResponseJson;

use OpenApi\Spec as OA;

class Controller
{
    #[OA\Response(
        response: 200,
        description: 'successful operation',
        content: [new OA\MediaType\Json(
            ref: '#/components/schemas/User',
        )],
    )]
    public function endpoint()
    {
    }
}

During processing the OA\JsonContent unwraps to OA\MediaType(mediaType="application/json", schema: OA\Schema(...)) and will generate the same output.

The same applies to OA\XmlContent.

OA\Property (spec only)

When using the OpenApi\Spec namespace, class properties and promoted constructor parameters that have an OA\Schema attribute do not need an explicit OA\Property attribute — it will be added automatically.

Verbose:

<?php

namespace Openapi\Snippets\Shortcuts\OptionalProperty;

use OpenApi\Spec as OA;

#[OA\Schema]
class Product
{
    #[OA\Property]
    #[OA\Schema(format: 'int64')]
    public int $id;
}

Shortcut:

<?php

namespace Openapi\Snippets\Shortcuts\OptionalProperty;

use OpenApi\Spec as OA;

#[OA\Schema]
class Product
{
    #[OA\Schema(format: 'int64')]
    public int $id;
}

Both produce the same output. The implicit OA\Property is inferred from the context (class property or promoted constructor parameter with an OA\Schema).

This also applies to OA\Schema subclasses like OA\Schema\Items:

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

The shortcut stops at methods, which supply no property name — getTags() is not tags, and the pipeline does not guess at accessor prefixes. A getter needs the explicit OA\Property, carrying the name:

#[OA\Property(property: 'tags')]
#[OA\Schema\Items(ref: Tag::class)]
public function getTags(): array

Without it the property is reported as missing its name and left out of the schema.

OA\Parameter

The OA\Parameter annotation requires specifying the in property to indicate where in the request the parameter is located.

Shortcut annotations are available for OA\PathParameter, OA\QueryParameter, OA\CookieParameter and OA\HeaderParameter.