Cookbook

Return JSON from an endpoint

For application/json content, OA\MediaType\Json takes the schema directly, without a nested OA\Schema. OA\MediaType\Xml is the same for XML.

<?php

namespace Openapi\Snippets\Cookbook\JsonResponse;

use OpenApi\Spec as OA;

class PetController
{
    #[OA\Operation\Get(path: '/pets/current')]
    #[OA\Response(
        response: 200,
        description: 'The current pet',
        content: [new OA\MediaType\Json(ref: '#/components/schemas/Pet')],
    )]
    public function current()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\JsonResponse;

use OpenApi\Attributes as OA;

class PetController
{
    #[OA\Get(path: '/pets/current')]
    #[OA\Response(
        response: 200,
        description: 'The current pet',
        content: new OA\JsonContent(ref: '#/components/schemas/Pet'),
    )]
    public function current()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\JsonResponse;

use OpenApi\Annotations as OA;

class PetController
{
    /**
     * @OA\Get(
     *     path="/pets/current",
     *     @OA\Response(
     *         response=200,
     *         description="The current pet",
     *         @OA\JsonContent(ref="#/components/schemas/Pet")
     *     )
     * )
     */
    public function current()
    {
    }
}

See OA\MediaType.

Document a list of objects

A property holding a list takes OA\Schema\Items, with the schema of one item as its arguments.

<?php

namespace Openapi\Snippets\Cookbook\ListOfObjects;

use OpenApi\Spec as OA;

#[OA\Schema(component: 'Pet')]
class Pet
{
    #[OA\Schema\Items(ref: '#/components/schemas/Tag')]
    public array $tags;
}

<?php

namespace Openapi\Snippets\Cookbook\ListOfObjects;

use OpenApi\Attributes as OA;

#[OA\Schema(schema: 'Pet')]
class Pet
{
    #[OA\Property(type: 'array', items: new OA\Items(ref: '#/components/schemas/Tag'))]
    public array $tags;
}

<?php

namespace Openapi\Snippets\Cookbook\ListOfObjects;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema(schema="Pet")
 */
class Pet
{
    /**
     * @OA\Property(type="array", @OA\Items(ref="#/components/schemas/Tag"))
     */
    public array $tags;
}

See OA\Schema subclasses.

Describe an object without a PHP class

Where a controller returns an array rather than an object of a class, properties can be keyed by property name. Classic has no short form for this.

<?php

namespace Openapi\Snippets\Cookbook\ObjectWithoutClass;

use OpenApi\Spec as OA;

class UserController
{
    #[OA\Operation\Get(path: '/users/me')]
    #[OA\Response(
        response: 200,
        description: 'The signed in user',
        content: [new OA\MediaType\Json(properties: [
            'name' => OA\Type::String,
            'email' => OA\Format::Email,
            'lastLogin' => OA\Format::DateTime,
        ])],
    )]
    public function me()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\ObjectWithoutClass;

use OpenApi\Attributes as OA;

class UserController
{
    #[OA\Get(path: '/users/me')]
    #[OA\Response(
        response: 200,
        description: 'The signed in user',
        content: new OA\JsonContent(properties: [
            new OA\Property(property: 'name', type: 'string'),
            new OA\Property(property: 'email', type: 'string', format: 'email'),
            new OA\Property(property: 'lastLogin', type: 'string', format: 'date-time'),
        ]),
    )]
    public function me()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\ObjectWithoutClass;

use OpenApi\Annotations as OA;

class UserController
{
    /**
     * @OA\Get(
     *     path="/users/me",
     *     @OA\Response(
     *         response=200,
     *         description="The signed in user",
     *         @OA\JsonContent(
     *             @OA\Property(property="name", type="string"),
     *             @OA\Property(property="email", type="string", format="email"),
     *             @OA\Property(property="lastLogin", type="string", format="date-time")
     *         )
     *     )
     * )
     */
    public function me()
    {
    }
}

A named schema works the same way, with an empty class as the anchor. An OA\Schema as the value nests an object:

<?php

namespace Openapi\Snippets\Cookbook\NamedObject;

use OpenApi\Spec as OA;

#[OA\Schema(
    component: 'Profile',
    properties: [
        'status' => OA\Type::String,
        'group' => new OA\Schema(properties: [
            'id' => OA\Type::Integer,
            'name' => OA\Type::String,
        ]),
    ],
)]
class Profile
{
}

<?php

namespace Openapi\Snippets\Cookbook\NamedObject;

use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: 'Profile',
    properties: [
        new OA\Property(property: 'status', type: 'string'),
        new OA\Property(property: 'group', type: 'object', properties: [
            new OA\Property(property: 'id', type: 'integer'),
            new OA\Property(property: 'name', type: 'string'),
        ]),
    ],
)]
class Profile
{
}

<?php

namespace Openapi\Snippets\Cookbook\NamedObject;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema(
 *     schema="Profile",
 *     @OA\Property(property="status", type="string"),
 *     @OA\Property(
 *         property="group",
 *         type="object",
 *         @OA\Property(property="id", type="integer"),
 *         @OA\Property(property="name", type="string")
 *     )
 * )
 */
class Profile
{
}

See Keyed properties.

Add constraints to a class property

A class property needs only an OA\Schema with the constraints. The name and the type come from the declaration. Spec also lists a typed property without a default as required.

<?php

namespace Openapi\Snippets\Cookbook\PropertyConstraints;

use OpenApi\Spec as OA;

#[OA\Schema(component: 'User')]
class User
{
    #[OA\Schema(maxLength: 50)]
    public string $name;

    #[OA\Schema(format: 'email')]
    public string $email;
}

<?php

namespace Openapi\Snippets\Cookbook\PropertyConstraints;

use OpenApi\Attributes as OA;

#[OA\Schema(schema: 'User')]
class User
{
    #[OA\Property(maxLength: 50)]
    public string $name;

    #[OA\Property(format: 'email')]
    public string $email;
}

<?php

namespace Openapi\Snippets\Cookbook\PropertyConstraints;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema(schema="User")
 */
class User
{
    /**
     * @OA\Property(maxLength=50)
     */
    public string $name;

    /**
     * @OA\Property(format="email")
     */
    public string $email;
}

An explicit OA\Property is needed only where the document uses a different name, such as full_name for $name, or on a getter. See OA\Property.

Document path, query and header parameters

OA\Parameter\Path, Query, Header and Cookie set in, and a path parameter is always required.

<?php

namespace Openapi\Snippets\Cookbook\Parameters;

use OpenApi\Spec as OA;

class PetController
{
    #[OA\Operation\Get(
        path: '/pets/{id}',
        parameters: [
            new OA\Parameter\Path(name: 'id', schema: new OA\Schema(type: 'integer')),
            new OA\Parameter\Query(name: 'fields', schema: new OA\Schema(type: 'string')),
            new OA\Parameter\Header(name: 'X-Request-Id', schema: new OA\Schema(type: 'string')),
        ],
    )]
    #[OA\Response(response: 200, description: 'The pet')]
    public function show()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\Parameters;

use OpenApi\Attributes as OA;

class PetController
{
    #[OA\Get(
        path: '/pets/{id}',
        parameters: [
            new OA\PathParameter(name: 'id', schema: new OA\Schema(type: 'integer')),
            new OA\QueryParameter(name: 'fields', schema: new OA\Schema(type: 'string')),
            new OA\HeaderParameter(name: 'X-Request-Id', schema: new OA\Schema(type: 'string')),
        ],
    )]
    #[OA\Response(response: 200, description: 'The pet')]
    public function show()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\Parameters;

use OpenApi\Annotations as OA;

class PetController
{
    /**
     * @OA\Get(
     *     path="/pets/{id}",
     *     @OA\PathParameter(name="id", @OA\Schema(type="integer")),
     *     @OA\Parameter(name="fields", in="query", @OA\Schema(type="string")),
     *     @OA\Parameter(name="X-Request-Id", in="header", @OA\Schema(type="string")),
     *     @OA\Response(response=200, description="The pet")
     * )
     */
    public function show()
    {
    }
}

See OA\Parameter.

Document several operations on one path

Each controller method gets the attribute for its HTTP method, OA\Operation\Get, OA\Operation\Post and so on.

<?php

namespace Openapi\Snippets\Cookbook\OperationsPerMethod;

use OpenApi\Spec as OA;

class PetController
{
    #[OA\Operation\Get(path: '/pets')]
    #[OA\Response(response: 200, description: 'All pets')]
    public function list()
    {
    }

    #[OA\Operation\Post(path: '/pets')]
    #[OA\Response(response: 201, description: 'The new pet')]
    public function create()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\OperationsPerMethod;

use OpenApi\Attributes as OA;

class PetController
{
    #[OA\Get(path: '/pets')]
    #[OA\Response(response: 200, description: 'All pets')]
    public function list()
    {
    }

    #[OA\Post(path: '/pets')]
    #[OA\Response(response: 201, description: 'The new pet')]
    public function create()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\OperationsPerMethod;

use OpenApi\Annotations as OA;

class PetController
{
    /**
     * @OA\Get(
     *     path="/pets",
     *     @OA\Response(response=200, description="All pets")
     * )
     */
    public function list()
    {
    }

    /**
     * @OA\Post(
     *     path="/pets",
     *     @OA\Response(response=201, description="The new pet")
     * )
     */
    public function create()
    {
    }
}

See OA\Operation\*.

x-tagGroups

OpenApi has the concept of grouping endpoints using tags. On top of that, some tools (redocly, for example) support further grouping via the vendor extension x-tagGroups.

<?php

namespace Openapi\Snippets\Cookbook\XTagGroups;

use OpenApi\Spec as OA;

#[OA\OpenApi(
    x: [
        'tagGroups' => [
            ['name' => 'User Management', 'tags' => ['Users', 'API keys', 'Admin']],
        ],
    ]
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\XTagGroups;

use OpenApi\Attributes as OA;

#[OA\OpenApi(
    x: [
        'tagGroups' => [
            ['name' => 'User Management', 'tags' => ['Users', 'API keys', 'Admin']],
        ],
    ]
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\XTagGroups;

use OpenApi\Annotations as OA;

/**
 * @OA\OpenApi(
 *     x={
 *         "tagGroups": {{"name": "User Management", "tags": {"Users", "API keys", "Admin"}}
 *         }
 *     }
 * )
 */
class OpenApiSpec
{
}

Adding examples to OA\Response

<?php

namespace Openapi\Snippets\Cookbook\ResponseExamples;

use OpenApi\Spec as OA;

#[OA\Schema(
    schema: 'Result',
    type: 'object',
    properties: [
        new OA\Property(property: 'success', schema: new OA\Schema(type: 'boolean')),
    ],
)]
class ResultModel
{
}

#[OA\Components]
class Controller
{
    #[OA\Response(
        response: 200,
        description: 'OK',
        content: [
            new OA\MediaType\Json(
                schema: new OA\Schema(
                    oneOf: [
                        new OA\Schema(ref: '#/components/schemas/Result'),
                        new OA\Schema(type: OA\Type::Boolean),
                    ]
                ),
                examples: [
                    new OA\Example(example: 'result', value: ['success' => true], summary: 'An result object.'),
                    new OA\Example(example: 'bool', value: false, summary: 'A boolean value.'),
                ],
            )],
    )]
    public function operation()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\ResponseExamples;

use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: 'Result',
    type: 'object',
    properties: [
        new OA\Property(property: 'success', type: 'boolean'),
    ],
)]
class ResultModel
{
}

class Controller
{
    #[OA\Response(
        response: 200,
        description: 'OK',
        content: new OA\JsonContent(
            oneOf: [
                new OA\Schema(ref: '#/components/schemas/Result'),
                new OA\Schema(type: 'boolean'),
            ],
            examples: [
                new OA\Examples(example: 'result', value: ['success' => true], summary: 'An result object.'),
                new OA\Examples(example: 'bool', value: false, summary: 'A boolean value.'),
            ],
        ),
    )]
    public function operation()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\ResponseExamples;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema(
 *     schema="Result",
 *     type="object",
 *     properties={
 *         @OA\Property(property="success", type="boolean"),
 *     },
 * )
 */
class ResultModel
{
}

class Controller
{
    /**
     * @OA\Response(
     *     response=200,
     *     description="OK",
     *     @OA\JsonContent(
     *         oneOf={
     *             @OA\Schema(ref="#/components/schemas/Result"),
     *             @OA\Schema(type="boolean")
     *         },
     *         @OA\Examples(example="result", value={"success": true}, summary="An result object."),
     *         @OA\Examples(example="bool", value=false, summary="A boolean value."),
     *     )
     * )
     */
    public function operation()
    {
    }
}

Adding examples to OA\Schema

A schema's examples is the JSON Schema keyword rather than a map of Example Objects, so it takes a list of values. OA\Schema\Items and OA\Schema\AdditionalProperties are schemas too and take the same list. A property takes it on the OA\Schema beside its OA\Property.

<?php

namespace Openapi\Snippets\Cookbook\SchemaExamples;

use OpenApi\Spec as OA;

#[OA\Schema(
    schema: 'Port',
    type: 'integer',
    examples: [80, 443],
)]
class PortModel
{
}

<?php

namespace Openapi\Snippets\Cookbook\SchemaExamples;

use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: 'Port',
    type: 'integer',
    examples: [80, 443],
)]
class PortModel
{
}

<?php

namespace Openapi\Snippets\Cookbook\SchemaExamples;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema(
 *     schema="Port",
 *     type="integer",
 *     examples={80, 443}
 * )
 */
class PortModel
{
}

A media type, parameter or header takes Example Objects instead.

Mode difference

In classic, OA\Property, OA\Items and OA\AdditionalProperties are schemas themselves and take the list directly. A nested OA\Examples is accepted there and contributes its value. The rest of it (the key, summary, description, externalValue) is dropped. In spec, an Example Object in the list is reported with a warning.

The keyword arrived in OpenAPI 3.1. Generating 3.0 from the same source drops the list in classic and carries the first value across as example in spec. Both warn.

External documentation

OpenApi allows a single reference to external documentation. This is a part of the top level OA\OpenApi.

<?php

namespace Openapi\Snippets\Cookbook\ExternalDocumentation;

use OpenApi\Spec as OA;

#[OA\ExternalDocumentation(
    description: 'More documentation here...',
    url: 'https://example.com/externaldoc1/',
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\ExternalDocumentation;

use OpenApi\Attributes as OA;

#[OA\OpenApi(
    externalDocs: new OA\ExternalDocumentation(
        description: 'More documentation here...',
        url: 'https://example.com/externaldoc1/',
    ),
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\ExternalDocumentation;

use OpenApi\Annotations as OA;

/**
 * @OA\OpenApi(
 *     @OA\ExternalDocumentation(
 *         description="More documentation here...",
 *         url="https://example.com/externaldoc1/"
 *     )
 * )
 */
class OpenApiSpec
{
}

TIP

If no OA\OpenApi is configured, swagger-php will create one automatically.

That means the above example would also work with just the OA\ExternalDocumentation.

#[OA\ExternalDocumentation(
    description: 'More documentation here...',
    url: 'https://example.com/externaldoc1/',
)]

Properties with union types

Sometimes properties or even lists (arrays) may contain data of different types. This can be expressed using oneOf.

<?php

namespace Openapi\Snippets\Cookbook\UnionTypes;

use OpenApi\Spec as OA;

#[OA\Schema(
    schema: 'StringList',
    properties: [
        new OA\Property(
            property: 'value',
            schema: new OA\Schema(
                type: 'array',
                items: new OA\Schema(
                    anyOf: [new OA\Schema(type: 'string')]
                ),
            ),
        ),
    ],
)]
#[OA\Schema(
    schema: 'String',
    properties: [
        new OA\Property(
            property: 'value',
            schema: new OA\Schema(type: 'string'),
        ),
],
)]
#[OA\Schema(
    schema: 'Object',
    properties: [
        new OA\Property(
            property: 'value',
            schema: new OA\Schema(type: OA\Type::Object),
        ),
],
)]
#[OA\Schema(
    schema: 'mixedList',
    properties: [
        new OA\Property(
            property: 'fields',
            schema: new OA\Schema(
                type: 'array',
                items: new OA\Schema(
                    oneOf: [
                    new OA\Schema(ref: '#/components/schemas/StringList'),
                    new OA\Schema(ref: '#/components/schemas/String'),
                    new OA\Schema(ref: '#/components/schemas/Object'),
                ],
                ),
            ),
        ),
    ],
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\UnionTypes;

use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: 'StringList',
    properties: [
        new OA\Property(
            property: 'value',
            type: 'array',
            items: new OA\Items(
                anyOf: [new OA\Schema(type: 'string')]
            ),
        ),
    ],
)]
#[OA\Schema(
    schema: 'String',
    properties: [
        new OA\Property(
            property: 'value',
            type: 'string',
        ),
],
)]
#[OA\Schema(
    schema: 'Object',
    properties: [
        new OA\Property(
            property: 'value',
            type: 'object',
        ),
],
)]
#[OA\Schema(
    schema: 'mixedList',
    properties: [
        new OA\Property(
            property: 'fields',
            type: 'array',
            items: new OA\Items(
                oneOf: [
                    new OA\Schema(ref: '#/components/schemas/StringList'),
                    new OA\Schema(ref: '#/components/schemas/String'),
                    new OA\Schema(ref: '#/components/schemas/Object'),
                ],
            ),
        ),
    ],
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\UnionTypes;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema(
 *     schema="StringList",
 *     @OA\Property(property="value", type="array", @OA\Items(anyOf={@OA\Schema(type="string")}))
 * )
 * @OA\Schema(
 *     schema="String",
 *     @OA\Property(property="value", type="string")
 * )
 * @OA\Schema(
 *     schema="Object",
 *     @OA\Property(property="value", type="object")
 * )
 * @OA\Schema(
 *     schema="mixedList",
 *     @OA\Property(property="fields", type="array", @OA\Items(oneOf={
 *         @OA\Schema(ref="#/components/schemas/StringList"),
 *         @OA\Schema(ref="#/components/schemas/String"),
 *         @OA\Schema(ref="#/components/schemas/Object")
 *     }))
 * )
 */
class OpenApiSpec
{
}

This will resolve into this YAML

openapi: 3.1.0
components:
  schemas:
    StringList:
      properties:
        value:
          type: array
          items:
            anyOf:
              -
                type: string
      type: object
    String:
      properties:
        value:
          type: string
      type: object
    Object:
      properties:
        value:
          type: object
      type: object
    mixedList:
      properties:
        fields:
          type: array
          items:
            oneOf:
              -
                $ref: '#/components/schemas/StringList'
              -
                $ref: '#/components/schemas/String'
              -
                $ref: '#/components/schemas/Object'
      type: object

Referencing a security scheme

An API might have zero or more security schemes. These are defined at the top level and vary from simple to complex:

<?php

namespace Openapi\Snippets\Cookbook\SecuritySchemas;

use OpenApi\Spec as OA;

#[OA\Security\Scheme\ApiKey(
    name: 'api_key',
    component: 'api_key',
    in: OA\SchemeIn::Header,
)]
#[OA\Security\Scheme\OAuth2(
    component: 'petstore_auth',
    flows: [
        new OA\Flow(
            flow: 'implicit',
            authorizationUrl: 'http://petstore.swagger.io/oauth/dialog',
            scopes: [
                'read:pets' => 'read your pets',
                'write:pets' => 'modify pets in your account',
            ],
        ),
    ],
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\SecuritySchemas;

use OpenApi\Attributes as OA;

#[OA\SecurityScheme(
    type: 'apiKey',
    name: 'api_key',
    in: 'header',
    securityScheme: 'api_key',
)]
#[OA\SecurityScheme(
    type: 'oauth2',
    securityScheme: 'petstore_auth',
    flows: [
        new OA\Flow(
            authorizationUrl: 'http://petstore.swagger.io/oauth/dialog',
            flow: 'implicit',
            scopes: [
                'read:pets' => 'read your pets',
                'write:pets' => 'modify pets in your account',
            ],
        ),
    ],
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\SecuritySchemas;

use OpenApi\Annotations as OA;

/**
 * @OA\SecurityScheme(
 *     type="apiKey",
 *     name="api_key",
 *     in="header",
 *     securityScheme="api_key"
 * )
 *
 * @OA\SecurityScheme(
 *     type="oauth2",
 *     securityScheme="petstore_auth",
 *     @OA\Flow(
 *         authorizationUrl="http://petstore.swagger.io/oauth/dialog",
 *         flow="implicit",
 *         scopes={
 *             "read:pets": "read your pets",
 *             "write:pets": "modify pets in your account"
 *         }
 *     )
 * )
 */
class OpenApiSpec
{
}

To declare an endpoint as secure and define what security schemes are available to authenticate a client, it needs to be added to the operation, for example:

<?php

namespace Openapi\Snippets\Cookbook\SecureEndpoint;

use OpenApi\Spec as OA;

class Controller
{
    #[OA\Operation\Get(
        path: '/api/secure/',
        summary: 'Requires authentication',
        security: [
            new OA\Security\Requirement(scheme: 'api_key', scopes: []),
        ],
    )]
    public function getSecurely()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\SecureEndpoint;

use OpenApi\Attributes as OA;

class Controller
{
    #[OA\Get(
        path: '/api/secure/',
        summary: 'Requires authentication',
        security: [
            [
                'api_key' => [],
            ],
        ],
    )]
    public function getSecurely()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\SecureEndpoint;

use OpenApi\Annotations as OA;

class Controller
{
    /**
     * @OA\Get(
     *     path="/api/secure/",
     *     summary="Requires authentication",
     *     security={ {"api_key": {}} }
     * )
     */
    public function getSecurely()
    {
        // ...
    }
}

Endpoints can support multiple security schemes and have custom options too:

<?php

namespace Openapi\Snippets\Cookbook\SecuritySchemaTips;

use OpenApi\Spec as OA;

class Controller
{
    #[OA\Operation\Get(
        path: '/api/secure/',
        summary: 'Requires authentication',
        security: [
            new OA\Security\Requirement(scheme: 'api_key', scopes: []),
            ['petstore_auth' => ['write:pets', 'read:pets']],
        ]
    )]
    public function secure()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\SecuritySchemaTips;

use OpenApi\Attributes as OA;

class Controller
{
    #[OA\Get(
        path: '/api/secure/',
        summary: 'Requires authentication',
        security: [
            ['api_key' => []],
            ['petstore_auth' => ['write:pets', 'read:pets']],
        ]
    )]
    public function secure()
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\SecuritySchemaTips;

use OpenApi\Annotations as OA;

class Controller
{
    /**
     * @OA\Get(
     *     path="/api/secure/",
     *     summary="Requires authentication",
     *     security={
     *         { "api_key": {} },
     *         { "petstore_auth": {"write:pets", "read:pets"} }
     *     }
     * )
     */
    public function secure()
    {
    }
}

See OA\Security\Requirement and OA\Security\Scheme\*.

File upload with headers

<?php

namespace Openapi\Snippets\Cookbook\FileUploadWithHeaders;

use OpenApi\Spec as OA;

class Controller
{
    #[OA\Operation\Post(
        path: '/v1/media/upload',
        summary: 'Upload document',
        description: '',
        tags: ['Media'],
        requestBody: new OA\RequestBody(
            required: true,
            content: [new OA\MediaType(
                mediaType: 'application/octet-stream',
                schema: new OA\Schema(
                    required: ['content'],
                    properties: [
                        new OA\Property(
                            property: 'content',
                            schema: new OA\Schema(
                                description: 'Binary content of file',
                                contentMediaType: 'application/octet-stream',
                            ),
                        ),
                    ],
                ),
            )],
        ),
    )]
    #[OA\Response(
        response: 200,
        description: 'Success',
    )]
    #[OA\Response(
        response: 400,
        description: 'Bad Request',
    )]
    public function upload()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\FileUploadWithHeaders;

use OpenApi\Attributes as OA;

class Controller
{
    #[OA\Post(
        path: '/v1/media/upload',
        summary: 'Upload document',
        description: '',
        tags: ['Media'],
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\MediaType(
                mediaType: 'application/octet-stream',
                schema: new OA\Schema(
                    required: ['content'],
                    properties: [
                        new OA\Property(
                            description: 'Binary content of file',
                            property: 'content',
                            type: 'string',
                            format: 'binary',
                        ),
                    ],
                ),
            ),
        ),
    )]
    #[OA\Response(
        response: 200,
        description: 'Success',
    )]
    #[OA\Response(
        response: 400,
        description: 'Bad Request',
    )]
    public function upload()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\FileUploadWithHeaders;

use OpenApi\Annotations as OA;

class Controller
{
    /**
     * @OA\Post(
     *     path="/v1/media/upload",
     *     summary="Upload document",
     *     description="",
     *     tags={"Media"},
     *     @OA\RequestBody(
     *         required=true,
     *         @OA\MediaType(
     *             mediaType="application/octet-stream",
     *             @OA\Schema(
     *                 required={"content"},
     *                 @OA\Property(
     *                     description="Binary content of file",
     *                     property="content",
     *                     type="string",
     *                     format="binary"
     *                 )
     *             )
     *         )
     *     ),
     *     @OA\Response(
     *         response=200, description="Success",
     *         @OA\Schema(type="string")
     *     ),
     *     @OA\Response(
     *         response=400, description="Bad Request"
     *     )
     * )
     */
    public function upload()
    {
        // ...
    }
}

Set the XML root name

OA\Xml may be used to set the XML root element for an XML response body

<?php

namespace Openapi\Snippets\Cookbook\XmlRootName;

use OpenApi\Spec as OA;

#[OA\Schema(
    schema: 'Error',
    properties: [new OA\Property(property: 'message')],
    xml: new OA\Xml(name: 'details'),
)]
#[OA\Operation\Post(
    path: '/foobar',
)]
#[OA\Response(
    response: 400,
    description: 'Request error',
    content: [new OA\MediaType(
        mediaType: 'application/xml',
        schema: new OA\Schema(
            ref: '#/components/schemas/Error',
            xml: new OA\Xml(name: 'error'),
        ),
    )],
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\XmlRootName;

use OpenApi\Attributes as OA;

#[OA\Schema(
    schema: 'Error',
    properties: [new OA\Property(property: 'message')],
    xml: new OA\Xml(name: 'details'),
)]
#[OA\Post(
    path: '/foobar',
)]
#[OA\Response(
    response: 400,
    description: 'Request error',
    content: new OA\XmlContent(
        ref: '#/components/schemas/Error',
        xml: new OA\Xml(name: 'error'),
    ),
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\XmlRootName;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema(
 *     schema="Error",
 *     @OA\Property(property="message"),
 *     @OA\Xml(name="details")
 * )
 * @OA\Post(
 *     path="/foobar",
 *     @OA\Response(
 *         response=400,
 *         description="Request error",
 *         @OA\XmlContent(ref="#/components/schemas/Error",
 *             @OA\Xml(name="error")
 *         )
 *     )
 * )
 */
class OpenApiSpec
{
}

upload multipart/form-data

Form posts are POST operations with a multipart/form-data request body. The relevant bit looks something like this

<?php

namespace Openapi\Snippets\Cookbook\UploadingMultipartFormData;

use OpenApi\Spec as OA;

class OpenApiSpec
{
    #[OA\Operation\Post(
        path: '/v1/user/update',
        summary: 'Form post',
        requestBody: new OA\RequestBody(
            content: [new OA\MediaType(
                mediaType: 'multipart/form-data',
                schema: new OA\Schema(
                    properties: [
                        new OA\Property(
                            property: 'name',
                            schema: new OA\Schema(description: 'the file name')
                        ),
                        new OA\Property(
                            property: 'avatar',
                            schema: new OA\Schema(
                                description: 'file to upload',
                                contentMediaType: 'application/octet-stream',
                            ),
                        ),
                    ],
                ),
            )],
        ),
    )]
    #[OA\Response(
        response: 200,
        description: 'Success'
    )]
    public function update()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\UploadingMultipartFormData;

use OpenApi\Attributes as OA;

class OpenApiSpec
{
    #[OA\Post(
        path: '/v1/user/update',
        summary: 'Form post',
        requestBody: new OA\RequestBody(
            content: new OA\MediaType(
                mediaType: 'multipart/form-data',
                schema: new OA\Schema(
                    properties: [
                        new OA\Property(
                            property: 'name',
                            description: 'the file name',
                        ),
                        new OA\Property(
                            description: 'file to upload',
                            property: 'avatar',
                            type: 'string',
                            format: 'binary',
                        ),
                    ],
                ),
            ),
        ),
    )]
    #[OA\Response(
        response: 200,
        description: 'Success'
    )]
    public function update()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\UploadingMultipartFormData;

use OpenApi\Annotations as OA;

class OpenApiSpec
{
    /**
     * @OA\Post(
     *     path="/v1/user/update",
     *     summary="Form post",
     *     @OA\RequestBody(
     *         @OA\MediaType(
     *             mediaType="multipart/form-data",
     *             @OA\Schema(
     *                 @OA\Property(property="name", description="the file name"),
     *                 @OA\Property(
     *                     description="file to upload",
     *                     property="avatar",
     *                     type="string",
     *                     format="binary",
     *                 ),
     *             )
     *         )
     *     ),
     *     @OA\Response(response=200, description="Success")
     * )
     */
    public function update()
    {
        // ...
    }
}

Default security scheme for all endpoints

Unless specified, each endpoint needs to declare what security schemes it supports. However, there is a way to also configure security schemes globally for the whole API.

This is done on OA\OpenApi:

<?php

namespace Openapi\Snippets\Cookbook\DefaultSecurity;

use OpenApi\Spec as OA;

#[OA\OpenApi]
#[OA\Security\Requirement(scheme: 'bearerAuth')]
#[OA\Security\Scheme\Http(component: 'bearerAuth', scheme: 'bearer')]
abstract class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\DefaultSecurity;

use OpenApi\Attributes as OAT;

#[OAT\OpenApi(
    security: [['bearerAuth' => []]]
)]
#[OAT\Components(
    securitySchemes: [
        new OAT\SecurityScheme(
            securityScheme: 'bearerAuth',
            type: 'http',
            scheme: 'bearer'
        ),
    ]
)]
class OpenApiSpec
{
}

<?php

namespace Openapi\Snippets\Cookbook\DefaultSecurity;

use OpenApi\Annotations as OA;

/**
 * @OA\OpenApi(
 *     security={{"bearerAuth": {}}}
 * )
 *
 * @OA\SecurityScheme(
 *     securityScheme="bearerAuth",
 *     type="http",
 *     scheme="bearer"
 * )
 */
class OpenApiSpec
{
}

See OA\Security\Requirement.

Documenting union type response data using oneOf

A response with either a single or a list of QualificationHolder's.

<?php

namespace Openapi\Snippets\Cookbook\OneOf;

use OpenApi\Spec as OA;

#[OA\Components]
class Controller
{
    #[OA\Response(
        response: 200,
        content: [new OA\MediaType(
            mediaType: 'application/json',
            schema: new OA\Schema(
                oneOf: [
                new OA\Schema(ref: '#/components/schemas/QualificationHolder'),
                new OA\Schema(
                    type: 'array',
                    items: new OA\Schema(ref: '#/components/schemas/QualificationHolder')
                ),
            ],
            ),
        )],
    )]
    public function index()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\OneOf;

use OpenApi\Attributes as OA;

class Controller
{
    #[OA\Response(
        response: 200,
        content: new OA\JsonContent(
            oneOf: [
                new OA\Schema(ref: '#/components/schemas/QualificationHolder'),
                new OA\Schema(
                    type: 'array',
                    items: new OA\Items(ref: '#/components/schemas/QualificationHolder')
                ),
            ],
        ),
    )]
    public function index()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\OneOf;

use OpenApi\Annotations as OA;

class Controller
{
    /**
     * @OA\Response(
     *     response=200,
     *     @OA\JsonContent(
     *         oneOf={
     *             @OA\Schema(ref="#/components/schemas/QualificationHolder"),
     *             @OA\Schema(
     *                 type="array",
     *                 @OA\Items(ref="#/components/schemas/QualificationHolder")
     *             )
     *         }
     *     )
     * )
     */
    public function index()
    {
        // ...
    }
}

Reusing responses

Global responses are found under /components/responses and can be referenced/shared just like schema definitions (models)

<?php

namespace Openapi\Snippets\Cookbook\ReusingResponse;

use OpenApi\Spec as OA;

#[OA\Response(
    response: 'product',
    description: 'All information about a product',
    content: [new OA\MediaType\Json(ref: '#/components/schemas/Product')],
)]
class ProductResponse
{
}

// ...

class ProductController
{
    #[OA\Operation\Get(
        tags: ['Products'],
        path: '/products/{product_id}',
    )]
    #[OA\Response(
        response: 'default',
        ref: '#/components/responses/product'
    )]
    public function getProduct($id)
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\ReusingResponse;

use OpenApi\Attributes as OA;

#[OA\Response(
    response: 'product',
    description: 'All information about a product',
    content: new OA\JsonContent(ref: '#/components/schemas/Product'),
)]
class ProductResponse
{
}

// ...

class ProductController
{
    #[OA\Get(
        tags: ['Products'],
        path: '/products/{product_id}',
    )]
    #[OA\Response(
        response: 'default',
        ref: '#/components/responses/product'
    )]
    public function getProduct($id)
    {
    }
}

<?php

namespace Openapi\Snippets\Cookbook\ReusingResponse;

use OpenApi\Annotations as OA;

/**
 * @OA\Response(
 *     response="product",
 *     description="All information about a product",
 *     @OA\JsonContent(ref="#/components/schemas/Product")
 * )
 */
class ProductResponse
{
}

// ...

class ProductController
{
    /**
     * @OA\Get(
     *     tags={"Products"},
     *     path="/products/{product_id}",
     *     @OA\Response(
     *         response="default",
     *         ref="#/components/responses/product"
     *     )
     * )
     */
    public function getProduct($id)
    {
    }
}

response parameter is always required

Even if referencing a shared response definition, the response parameter is still required.

mediaType="/"

Using */* as mediaType is not possible with docblock annotations. Attributes do not have this problem.

Example:

/**
 * @OA\MediaType(
 *     mediaType="*/*",
 *     @OA\Schema(type="string",format="binary")
 * )
 */

The doctrine annotations library used for parsing annotations does not handle this and will interpret the */ bit as the end of the comment.

Using just * or application/octet-stream might be usable workarounds.

Callbacks

The API does include basic support for callbacks. However, this needs to be set up mostly manually.

Example

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

#[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'
                                        ),
                                    ],
                                ),
                            ),
                        ],
                    ),
                ],
            ],
        ],
    ],
    // ...
)]

/**
 * @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"
 *                      }
 *                  }
 *              }
 *         }
 *     }
 *     ...
 * )
 */

Using class name as a type instead of references

Typically, when referencing schemas this is done using $ref's

#[OA\Schema(component: 'user')]
class User
{
}

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

This works but is not very convenient.

First, when using custom schema names (component: 'user'), this needs to be taken into account everywhere. Secondly, having to write ref: '#/components/schemas/user' is tedious and error-prone.

Using attributes, all this changes as we can take advantage of PHP itself by referring to a schema by its (fully qualified) class name.

With the same User schema as before, the Book::author property could be written in a few different ways

    #[OA\Property]
    public User $author;

or

    /**
     * @var User
     */
    #[OA\Property]
    public $author;

or

    #[OA\Schema(ref: User::class)]
    public $author;

    #[OAT\Property()]
    public User $author;

or

    /**
     * @var User
     */
    #[OAT\Property()]
    public $author;

or

    #[OAT\Property(type: User::class)]
    public $author;

    /** @OA\Property() */
    public User $author;

or

    /**
     * @var User
     * @OA\Property()
     */
    public $author;

Enums

As of PHP 8.1 there is native support for enum's.

swagger-php supports enums in much the same way as class names can be used to reference schemas.

Example

<?php

namespace Openapi\Snippets\Cookbook\Enums;

use OpenApi\Spec as OA;

#[OA\Schema]
enum State
{
    case OPEN;
    case MERGED;
    case DECLINED;
}

#[OA\Schema]
class PullRequest
{
    #[OA\Property]
    public State $state;
}

<?php

namespace Openapi\Snippets\Cookbook\Enums;

use OpenApi\Attributes as OA;

#[OA\Schema]
enum State
{
    case OPEN;
    case MERGED;
    case DECLINED;
}

#[OA\Schema]
class PullRequest
{
    #[OA\Property]
    public State $state;
}

<?php

namespace Openapi\Snippets\Cookbook\Enums;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema()
 */
enum State
{
    case OPEN;
    case MERGED;
    case DECLINED;
}

/**
 * @OA\Schema
 */
class PullRequest
{
    /** @OA\Property */
    public State $state;
}

However, in this case the schema generated for State will be an enum:

components:
  schemas:
    PullRequest:
      properties:
        state:
          $ref: '#/components/schemas/State'
      type: object
    State:
      type: string
      enum:
        - OPEN
        - MERGED
        - DECLINED

Multi value query parameter: &q[]=1&q[]=1

PHP allows having query parameters multiple times in the url and will combine the values to an array if the parameter name uses trailing []. In fact, it is possible to create nested arrays too by using more than one pair of [].

In terms of OpenAPI, the parameters can be considered a single parameter with a list of values.

<?php

namespace Openapi\Snippets\Cookbook\MultiValueQueryParameter;

use OpenApi\Spec as OA;

class Controller
{
    #[OA\Operation\Get(
        path: '/api/endpoint',
        description: 'The endpoint',
        operationId: 'endpoint',
        tags: ['endpoints'],
        parameters: [
            new OA\Parameter\Query(
                name: 'things[]',
                description: 'A list of things.',
                required: false,
                schema: new OA\Schema\Items(type: OA\Type::Integer),
            ),
        ],
    )]
    #[OA\Response(response: '200', description: 'All good')]
    public function endpoint()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\MultiValueQueryParameter;

use OpenApi\Attributes as OA;

class Controller
{
    #[OA\Get(
        path: '/api/endpoint',
        description: 'The endpoint',
        operationId: 'endpoint',
        tags: ['endpoints'],
        parameters: [
            new OA\Parameter(
                name: 'things[]',
                in: 'query',
                description: 'A list of things.',
                required: false,
                schema: new OA\Schema(
                    type: 'array',
                    items: new OA\Items(type: 'integer')
                )
            ),
        ],
    )]
    #[OA\Response(response: '200', description: 'All good')]
    public function endpoint()
    {
        // ...
    }
}

<?php

namespace Openapi\Snippets\Cookbook\MultiValueQueryParameter;

use OpenApi\Annotations as OA;

class Controller
{
    /**
     * @OA\Get(
     *     path="/api/endpoint",
     *     description="The endpoint",
     *     operationId="endpoint",
     *     tags={"endpoints"},
     *     @OA\Parameter(
     *         name="things[]",
     *         in="query",
     *         description="A list of things.",
     *         required=false,
     *         @OA\Schema(
     *             type="array",
     *             @OA\Items(type="integer")
     *         )
     *     ),
     *     @OA\Response(response="200", description="All good")
     * )
     */
    public function endpoint()
    {
        // ...
    }
}

The corresponding bit of the spec will look like this:

      parameters:
        -
          name: 'things[]'
          in: query
          description: 'A list of things.'
          required: false
          schema:
            type: array
            items:
              type: integer

swagger-ui will show a form that allows to add/remove items (integer values in this case) to/from a list and post those values as something like ?things[]=1&things[]=2&things[]=0

See OA\Parameter\* and OA\Schema subclasses.

Custom response classes

Even with using refs, there is a bit of overhead in sharing responses. One way around that is to write your own response classes. The beauty is that in your custom __construct() method you can prefill as much as you need.

Example:

use OpenApi\Spec as OA;

#[\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\Operation\Get(path: '/foo', responses: [new BadRequest()])]
    public function get()
    {
    }

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

Classic attributes and docblock annotations

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

Docblock annotations only?

If you are only interested in docblock annotations, you can leave out the attribute setup line (#[\Attribute...) for BadRequest.

Furthermore, your custom docblock annotations should extend from the OpenApi\Annotations namespace.

Annotating class constants

<?php

namespace Openapi\Snippets\Cookbook\ClassConstants;

use OpenApi\Spec as OA;

#[OA\Schema]
class Airport
{
    #[OA\Property(property: 'kind')]
    public const KIND = 'Airport';
}

<?php

namespace Openapi\Snippets\Cookbook\ClassConstants;

use OpenApi\Attributes as OA;

#[OA\Schema]
class Airport
{
    #[OA\Property(property: 'kind')]
    public const KIND = 'Airport';
}

<?php

namespace Openapi\Snippets\Cookbook\ClassConstants;

use OpenApi\Annotations as OA;

/**
 * @OA\Schema
 */
class Airport
{
    /** @OA\Property(property="kind") */
    public const KIND = 'Airport';
}

The const property is supported in OpenApi 3.1.0.

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

For 3.0.0 this is serialized into a single value enum.

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

Add a hand-written document

Some parts of an API have no PHP code to put attributes on, webhooks for example. Write them as an OpenAPI 3.1 document and pass it to the Builder with withDocument(). A $ref in it can point at a schema built from a class:

openapi: 3.1.0
info:
  title: Shop
  version: 1.0.0
webhooks:
  orderPlaced:
    post:
      summary: An order was placed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Received

<?php declare(strict_types=1);

namespace OpenApi\Snippets\Guide\Cookbook\Documents;

use OpenApi\Spec as OA;

#[OA\Schema(description: 'An order')]
class Order
{
    #[OA\Property]
    public int $id;

    #[OA\Property]
    public string $status;
}

class OrderController
{
    #[OA\Operation\Get(path: '/orders/latest', operationId: 'latestOrder', responses: [
        new OA\Response(response: 200, description: 'The latest order', content: [new OA\MediaType\Json(schema: new OA\Schema(ref: Order::class))]),
    ])]
    public function latest(): void
    {
    }
}

<?php declare(strict_types=1);

namespace OpenApi\Snippets\Guide\Cookbook\Documents;

use OpenApi\Builder;

function build(): Builder
{
    return (new Builder())
        ->addSource(__DIR__ . '/models.php')
        ->withDocument(__DIR__ . '/webhooks.yaml');
}

gives:

openapi: 3.1.0
info:
  title: Shop
  version: 1.0.0
paths:
  /orders/latest:
    get:
      operationId: latestOrder
      responses:
        '200':
          description: 'The latest order'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      description: 'An order'
      properties:
        id:
          type: integer
        status:
          type: string
      required:
        - id
        - status
webhooks:
  orderPlaced:
    post:
      summary: 'An order was placed'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Received

Where a document and the attributes describe the same thing, the attributes win. The details, and what a document cannot hold, are in Documents.

Build parts of a document for another one

An integration that keeps a document of its own can still take parts of it from spec attributes: a model's schema, or a parameter. Build each part with a Builder, so it goes through the whole pipeline: the resolver, the augmenters and any augmenter the integration registers. Compiling the attributes directly skips all of that.

<?php declare(strict_types=1);

namespace OpenApi\Snippets\Guide\Cookbook\Fragments;

use OpenApi\Augmenter\Cleanup;
use OpenApi\Builder;
use OpenApi\Builder\Mode;
use OpenApi\Contracts\AttributeInterface;
use OpenApi\Spec as OA;
use OpenApi\Specification;

/**
 * A new builder for each part; the host's own augmenters are registered here too.
 */
function partBuilder(): Builder
{
    return (new Builder())
        ->setMode(Mode::SPEC)
        ->setVersion('3.1.0')
        ->withSpecification(fn (Specification $specification) => $specification->add(
            (new OA\Info(title: 'Part', version: '1.0.0'))->setMeta('host.filler', true)
        ));
}

/**
 * The schema of a class with `#[OA\Schema]`.
 *
 * @param class-string $class
 *
 * @return array<string, mixed>
 */
function buildModel(string $class): array
{
    $reflector = new \ReflectionClass($class);
    $document = partBuilder()
        ->addSource($reflector)
        ->withSpecification(function (Specification $specification): void {
            foreach ($specification->schemas as $schema) {
                $schema->setMeta(Cleanup::class, false);
            }
        })
        ->build()
        ->toArray();

    return $document['components']['schemas'][$reflector->getShortName()];
}

/**
 * A part keyed with `component:`, from the given `components` bucket.
 *
 * @return array<string, mixed>
 */
function buildPart(AttributeInterface $part, string $bucket): array
{
    $document = partBuilder()
        ->withSpecification(fn (Specification $specification) => $specification->add($part->setMeta(Cleanup::class, false)))
        ->build()
        ->toArray();

    return $document['components'][$bucket][$part->component];
}

Nothing references a part, so the Cleanup augmenter would remove it as unused. Each part is marked with setMeta(Cleanup::class, false), which Cleanup leaves alone, together with what the part references.

The builder:

• adds an OA\Info, since a document without one reports an error. It is filler, marked with setMeta() under a key the integration owns, so its own augmenters can leave it alone.
• is new for every part. A Builder builds one document, and building a few classes is cheap.

The integration then reads each part by its key and ignores the rest of the document. For the classes below, buildModel(User::class) and a path parameter passed to buildPart():

<?php declare(strict_types=1);

namespace OpenApi\Snippets\Guide\Cookbook\Fragments;

use OpenApi\Spec as OA;

#[OA\Schema(description: 'A registered user')]
class User
{
    /**
     * @example 7
     */
    #[OA\Property(schema: new OA\Schema(readOnly: true))]
    public int $id;

    #[OA\Property(property: 'display_name')]
    public ?string $name = null;

    #[OA\Property]
    public Address $address;
}

#[OA\Schema]
class Address
{
    #[OA\Property]
    public string $street;
}

buildPart(new OA\Parameter\Path(name: 'id', schema: new OA\Schema(type: 'integer'), component: 'id'), 'parameters');

give:

User:
  type: object
  description: 'A registered user'
  properties:
    id:
      type: integer
      readOnly: true
      example: 7
    display_name:
      type:
        - string
        - 'null'
    address:
      $ref: '#/components/schemas/Address'
  required:
    - id
    - address
id:
  name: id
  in: path
  required: true
  schema:
    type: integer

A $ref in a part points into the components of the build that made it, as #/components/schemas/Address does here. The integration maps it to the name it uses for that class in its own document.

At version 3.0.0 the build also reports an error that paths is required. An OA\Operation added as filler next to the OA\Info removes the error.

See Contributing to the Specification.