Response Schema Inference from Eloquent API Resources

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 — all through static AST traversal with no database connection and no application boot required.

Supported Return Patterns

JsonResource Instances

When a controller returns a JsonResource instance directly or via a static factory, Geni inspects the toArray() method of that resource class:

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

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

Given this 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')),
        ];
    }
}

Geni walks the returned array, resolves each value’s type, and constructs an object schema with matching property names and inferred types.

Resource Collections

Geni recognizes both Resource::collection() calls and custom collection classes. The item resource schema is inferred and wrapped in an array response:

public function index()
{
    return ArticleResource::collection(Article::all());
}

LengthAwarePaginator

When a controller calls paginate() on an Eloquent query or returns a paginated resource, Geni infers the complete standard Laravel pagination envelope:

public function index()
{
    return ArticleResource::collection(Article::paginate());
}

The generated response schema includes:

data: Array of item schemas (e.g., ArticleResource objects).
links: Navigation URLs — first, last, prev, next.
meta: Pagination metadata — current_page, from, last_page, path, per_page, to, total.

Direct Eloquent Models

If a controller directly returns an Eloquent model, Geni resolves the underlying table schema from your migrations and builds an object schema containing all model columns, respecting $hidden attributes where statically detectable:

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

Raw `response()->json()` Calls

When a controller returns a literal array via response()->json(), Geni reconstructs an object schema with matching literal keys and inferred value types:

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

The resulting schema includes status as type: string and timestamp as type: integer.

Component Reusability

Whenever Geni analyzes a JsonResource or Eloquent model, it registers the resulting schema under components.schemas in the OpenAPI document (e.g., #/components/schemas/ArticleResource). Subsequent references to the same resource resolve to a $ref rather than an inline schema, keeping your OpenAPI specification concise and free of duplicate definitions.

Getting Started

Core Concepts

Integrations

Annotations

Guides

Reference

Response Schema Inference from Eloquent API Resources

Supported Return Patterns

JsonResource Instances

Resource Collections

LengthAwarePaginator

Direct Eloquent Models

Raw `response()->json()` Calls

Component Reusability

​Supported Return Patterns

​JsonResource Instances

​Resource Collections

​LengthAwarePaginator

​Direct Eloquent Models

​Raw response()->json() Calls

​Component Reusability

Supported Return Patterns

JsonResource Instances

Resource Collections

LengthAwarePaginator

Direct Eloquent Models

Raw `response()->json()` Calls

Component Reusability