Attributes

PHP Attributes are the preferred way to annotate your code.

::: tip Namespace Using a namespace alias simplifies typing and improves readability.

All attributes are in the OpenApi\Attributes namespace.

use OpenApi\Attributes as OA;

#[OA\Info(/*...*/)]

:::

Nesting

Similar to annotations attributes can be top level or nested. However, attributes may be put at the same level if there is no ambiguity. swagger-php will then merge attributes according to the defined rules about parent/child relationships.

Example

Nested:

    #[OA\Get(
        path: '/api/users',
        responses: [
            new OA\Response(response: 200, description: 'OK'),
            new OA\Response(response: 401, description: 'Not allowed'),
        ]
    )]
    public function users() { /* ... */ }

Not nested:

    #[OA\Get(path: '/api/users')]
    #[OA\Response(response: 200, description: 'OK')]
    #[OA\Response(response: 401, description: 'Not allowed')]
    public function users() { /* ... */ }

Depending on how much nesting there is this can make things a bit simpler and easier to read.

::: warning Top level only Automatic merging of attributes works only at the top level - in the example that would be the method users(). :::