📘 Documentación con API Resources

📘 Documentación con API Resources

En Laravel, los API Resources permiten transformar los modelos y colecciones de Eloquent en respuestas JSON bien estructuradas y coherentes. Son ideales para documentar y mantener consistencia en la salida de datos de una API REST.

🎯 ¿Qué es un API Resource?

Un Resource es una clase que define cómo debe verse un modelo cuando se devuelve en formato JSON. Por ejemplo, si tienes un modelo User, puedes crear un UserResource para decidir qué campos incluir o cómo formatearlos.

php artisan make:resource UserResource

📂 Ubicación de los Resources

Por defecto, Laravel los crea dentro de app/Http/Resources. Cada clase hereda de Illuminate\Http\Resources\Json\JsonResource.

🧩 Ejemplo básico de un Resource

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'nombre' => $this->name,
            'email' => $this->email,
            'creado_en' => $this->created_at->format('d/m/Y'),
        ];
    }
}

🚀 Usando el Resource en un controlador

use App\Http\Resources\UserResource;
use App\Models\User;

public function show($id)
{
    $usuario = User::findOrFail($id);
    return new UserResource($usuario);
}

La respuesta será un JSON estructurado según la definición del Resource. Si deseas devolver varios usuarios, puedes usar UserResource::collection().

return UserResource::collection(User::all());

🧱 Ventajas principales

• Controlas exactamente qué datos se exponen en la API.
• Facilita mantener consistencia entre distintos endpoints.
• Permite anidar relaciones (por ejemplo, incluir posts dentro de un usuario).
• Ayuda a documentar y mantener el formato de salida del API.

🔗 Anidando Resources

Puedes incluir otros recursos dentro del JSON para relaciones:

return [
    'id' => $this->id,
    'nombre' => $this->name,
    'posts' => PostResource::collection($this->posts),
];

🧠 Tip

Laravel también permite devolver metadatos adicionales con el método with():

public function with(Request $request)
{
    return ['version' => '1.0.0'];
}

Esto es útil para incluir información general de la API o de la respuesta.

🏠 Volver al Índice ➡️ Siguiente tema: 📡 Consumo de APIs desde el Frontend