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

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

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

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

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

use OpenApi\Annotations as OA;

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

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

The same applies to OA\XmlContent.

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.