Attributes

composer require langsys/openapi-docs-generator Copy

PHP 8.1+ Laravel 10 / 11

Packagist ↗ GitHub ↗

Control how properties appear in the generated schema using PHP attributes on your DTO properties.

#[Example]

use Langsys\OpenApiDocsGenerator\Generators\Attributes\Example;

class UserData extends Data
{
    public function __construct(
        #[Example(42)]
        public int $id,

        #[Example('[email protected]')]
        public string $email,
    ) {}
}

Prefix the example value with : to call a Faker method directly:

#[Example(':sentence')]
public string $title,

#[Example(':numberBetween', arguments: [1, 100])]
public int $score,

#[Description] / #[Omit]

use Langsys\OpenApiDocsGenerator\Generators\Attributes\Description;
use Langsys\OpenApiDocsGenerator\Generators\Attributes\Omit;

class UserData extends Data
{
    public function __construct(
        #[Description('The unique user identifier')]
        public int $id,

        #[Omit]
        public string $internal_token,  // will NOT appear in the schema
    ) {}
}

#[GroupedCollection]

Mark a property as a grouped/dictionary structure. The argument is the key used in the example.

use Langsys\OpenApiDocsGenerator\Generators\Attributes\GroupedCollection;

class TranslationData extends Data
{
    public function __construct(
        #[GroupedCollection('en')]
        #[Example('Hello')]
        public array $greetings,
    ) {}
}

Produces { "type": "object", "example": { "en": "Hello" } }. Combined with a typed collection it produces a dictionary-of-arrays instead.

#[ItemType] / #[OneOfItemsFrom]

Declare a polymorphic array whose items can be one of several DTO variants — block-based content, event envelopes, tagged unions.

• #[ItemType('group', ?handle)] on a Data class registers that class as a variant. The optional handle defaults to the snake-cased basename with Resource / Data stripped.
• #[OneOfItemsFrom('group')] on an array property emits array<oneOf<...>> where each member is a wrapper schema { type: <handle>, data: <Variant> }.

use Langsys\OpenApiDocsGenerator\Generators\Attributes\ItemType;
use Langsys\OpenApiDocsGenerator\Generators\Attributes\OneOfItemsFrom;

#[ItemType('blocks')] // handle inferred as "paragraph"
class ParagraphResource extends Data { /* ... */ }

#[ItemType('blocks', 'picture')]
class ImageResource extends Data { /* ... */ }

class BlockContainerResource extends Data
{
    public function __construct(
        public string $title,
        #[OneOfItemsFrom('blocks')]
        public array $content,
    ) {}
}

Abstract Data subclasses are skipped from auto-schema generation.