PHP 8 Attributes

Explicit OpenAPI overrides and enhancements using native PHP 8 attributes.

Overview

While Geni infers most schemas automatically, PHP 8 attributes allow you to override, enrich, or explicitly document specific endpoint behaviors.

All attributes live under the namespace Geni\Laravel\Attributes\*.

If you are migrating from Scramble, Geni supports identical attribute names and parameters; simply update your use statements from Dedoc\Scramble\Attributes\* to Geni\Laravel\Attributes\*.

Available Attributes

Endpoint Metadata

use Geni\Laravel\Attributes\Endpoint;
use Geni\Laravel\Attributes\Group;
use Geni\Laravel\Attributes\Hidden;

#[Group('Articles', 'Endpoints for managing blog articles')]
class ArticleController
{
    #[Endpoint(
        title: 'Publish an article',
        description: 'Changes article status to published and notifies subscribers.',
        operationId: 'articles.publish',
        deprecated: false
    )]
    public function publish(Article $article) {}

    #[Hidden]
    public function internalWebhook() {}
}

Parameter Documentation

use Geni\Laravel\Attributes\PathParameter;
use Geni\Laravel\Attributes\QueryParameter;
use Geni\Laravel\Attributes\HeaderParameter;

class ArticleController
{
    #[QueryParameter(
        name: 'include_drafts',
        description: 'Whether to include unpublished draft articles.',
        type: 'boolean',
        default: false
    )]
    #[HeaderParameter(
        name: 'X-Client-Version',
        description: 'Client application version identifier.',
        type: 'string'
    )]
    public function index() {}
}

Response Overrides

use Geni\Laravel\Attributes\Response;
use Geni\Laravel\Attributes\Example;

class ArticleController
{
    #[Response(
        status: 201,
        description: 'Article successfully created.',
        type: ArticleResource::class
    )]
    #[Response(
        status: 422,
        description: 'Validation failed.'
    )]
    public function store() {}
}

Body Parameter Overrides

use Geni\Laravel\Attributes\BodyParameter;

class StoreArticleRequest extends FormRequest
{
    #[BodyParameter(
        name: 'title',
        description: 'The unique title for the article.',
        example: 'Getting Started with Geni'
    )]
    public function rules(): array
    {
        return [
            'title' => 'required|string',
        ];
    }
}

Attribute Reference Table

Attribute	Target	Purpose
#[Endpoint(title, description, ...)]	Method	Define operation summary, description, and operationId
#[Group(name, description)]	Class or Method	Group operations under OpenAPI tags
#[Hidden]	Class or Method	Exclude operation or entire controller from docs
#[ExcludeRouteFromDocs]	Method	Exclude specific route
#[ExcludeAllRoutesFromDocs]	Class	Exclude all routes in controller
#[QueryParameter(name, ...)]	Method	Explicitly document or override a query parameter
#[PathParameter(name, ...)]	Method	Explicitly document or override a path parameter
#[HeaderParameter(name, ...)]	Method	Explicitly document or override a header parameter
#[BodyParameter(name, ...)]	Method or FormRequest	Add descriptions or examples to request body fields
#[Response(status, description, type)]	Method	Explicitly define or override an HTTP response schema
#[IgnoreParam(name)]	Method	Remove an inferred parameter or field from documentation
#[IgnoreResponse(status)]	Method	Remove an inferred response code
#[SchemaName(name)]	Class	Customize the component schema name in OpenAPI