> ## Documentation Index
> Fetch the complete documentation index at: https://geni.masiting.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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\*`.

<Note>
  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\*`.
</Note>

## Available Attributes

### Endpoint Metadata

```php theme={null}
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

```php theme={null}
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

```php theme={null}
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

```php theme={null}
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           |