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

public function show(Article $article): ArticleResource
{
    return new ArticleResource($article);
}

Or via static factory:

public function show(Article $article)
{
    return ArticleResource::make($article);
}

Geni inspects the toArray() method of ArticleResource:

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:

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:

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:

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():

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.