Enrich OpenAPI Documentation with PHP 8 Attributes

While Geni infers most schemas automatically through static analysis, PHP 8 native attributes give you fine-grained control over specific endpoint behaviors — letting you override inferred values, fill in gaps, or explicitly define responses and parameters that cannot be detected from source code alone. All attributes live under the Geni\Laravel\Attributes\* namespace and are applied directly to controller classes, methods, or Form Request classes.

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\* — no other changes are required.

Endpoint Metadata

Use #[Endpoint], #[Group], and #[Hidden] to control how operations and controllers appear in your generated documentation. Apply #[Group] at the class level to tag all routes in a controller together, #[Endpoint] on individual methods to set a human-readable title and description, and #[Hidden] to exclude an operation entirely.

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 #[QueryParameter], #[PathParameter], and #[HeaderParameter] to explicitly document or override parameters that Geni cannot fully infer — for example, optional query filters, custom headers, or path segments resolved outside of route model binding.

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 #[Response] to explicitly define or override HTTP response schemas when Geni’s inference is incomplete or when you need to document multiple response codes on the same endpoint. Stack multiple #[Response] attributes on a single method to cover every status code your endpoint can return.

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 #[BodyParameter] on a Form Request’s rules() method to attach descriptions or example values to individual request body fields. This is particularly useful when your validation rules alone do not convey enough context for API consumers.

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

The table below lists every attribute Geni supports, where you can apply it, and what it controls in the generated OpenAPI output.

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 a specific route
`#[ExcludeAllRoutesFromDocs]`	Class	Exclude all routes in a 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

Getting Started

Core Concepts

Integrations

Annotations

Guides

Reference

Enrich OpenAPI Documentation with PHP 8 Attributes

Endpoint Metadata

Parameter Documentation

Response Overrides

Body Parameter Overrides

Attribute Reference

​Endpoint Metadata

​Parameter Documentation

​Response Overrides

​Body Parameter Overrides

​Attribute Reference

Endpoint Metadata

Parameter Documentation

Response Overrides

Body Parameter Overrides

Attribute Reference