> ## 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.

# Eloquent & API Resources

> Static response schema inference for Laravel JsonResources and Eloquent models.

## Overview

Geni automatically infers response schemas by analyzing what your controller actions return. It resolves `JsonResource` classes, Resource Collections, Eloquent models, paginators, plain PHP objects, and raw JSON responses.

## Supported Return Patterns

### 1. `JsonResource` Instances

```php theme={null}
public function show(Article $article): ArticleResource
{
    return new ArticleResource($article);
}
```

Or via static factory:

```php theme={null}
public function show(Article $article)
{
    return ArticleResource::make($article);
}
```

Geni inspects the `toArray()` method of `ArticleResource`:

```php theme={null}
class ArticleResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
            'created_at' => $this->created_at,
            'author' => new UserResource($this->whenLoaded('author')),
        ];
    }
}
```

### 2. Resource Collections

Geni recognizes both `Resource::collection()` calls and custom collection classes:

```php theme={null}
public function index()
{
    return ArticleResource::collection(Article::all());
}
```

Geni wraps the item schema in an array response or paginated envelope.

### 3. LengthAwarePaginator

When a controller calls `paginate()` on an Eloquent query or returns a paginated resource:

```php theme={null}
public function index()
{
    return ArticleResource::collection(Article::paginate());
}
```

Geni infers the complete standard Laravel pagination envelope:

* `data`: Array of item schemas
* `links`: Navigation URLs (`first`, `last`, `prev`, `next`)
* `meta`: Pagination metadata (`current_page`, `from`, `last_page`, `path`, `per_page`, `to`, `total`)

### 4. Direct Eloquent Models

If a controller directly returns an Eloquent model:

```php theme={null}
public function show(Article $article): Article
{
    return $article;
}
```

Geni resolves the underlying table schema from your migrations and constructs an object schema containing all model columns, respecting `$hidden` attributes where detectable.

### 5. Raw `response()->json()` Calls

If a controller returns a literal array via `response()->json()`:

```php theme={null}
public function ping()
{
    return response()->json([
        'status' => 'ok',
        'timestamp' => 1714500000,
    ]);
}
```

Geni reconstructs an object schema with matching literal keys and inferred value types.

## Component Reusability (`#/components/schemas`)

Whenever a `JsonResource` or Eloquent model is analyzed, Geni registers the schema under `components.schemas` in the OpenAPI document (e.g., `#/components/schemas/ArticleResource`).

This prevents duplicate definitions and keeps your OpenAPI specification concise and readable.