PHP code example of jkbennemann / laravel-api-documentation

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

jkbennemann / laravel-api-documentation example snippets

'documentation' => [
    'driver'     => 'local',
    'root'       => public_path('docs'),
    'url'        => env('APP_URL') . '/docs',
    'visibility' => 'public',
],

// config/laravel-api-documentation.php
'storage' => [
    'disk' => 'documentation',
    'filename' => 'api-documentation.json',
],

// config/laravel-api-documentation.php
'ui' => [
    'enabled' => true,
    'swagger' => true,
    'redoc' => true,
],

use JkBennemann\LaravelApiDocumentation\Attributes\Tag;
use JkBennemann\LaravelApiDocumentation\Attributes\Summary;
use JkBennemann\LaravelApiDocumentation\Attributes\Description;
use JkBennemann\LaravelApiDocumentation\Attributes\AdditionalDocumentation;
use JkBennemann\LaravelApiDocumentation\Attributes\DataResponse;

#[Tag('Authentication')]
#[Summary('Login a user')]
#[Description('Logs a user in with email and password credentials.')]
#[AdditionalDocumentation(url: 'https://example.com/auth', description: 'Auth documentation')]
#[DataResponse(200, description: 'Logged in user information', resource: UserResource::class)]
#[DataResponse(401, description: 'Failed Authentication', resource: ['error' => 'string'])]
public function login(LoginRequest $request)
{
    // Method implementation
}

# SampleController.php
use JkBennemann\LaravelApiDocumentation\Attributes\DataResponse;

//..
#[DataResponse(200, description: 'Logged in user information', resource: UserResource::class, headers: ['X-Token' => 'Token for the user to be used to issue API calls',])]
#[DataResponse(401, description: 'Failed Authentication', resource: ['error' => 'string'])]
public function index()
{
    //...
}

# UserController.php
use JkBennemann\LaravelApiDocumentation\Attributes\PathParameter;

//..
#[PathParameter(name: 'id', type: 'string', format: 'uuid', description: 'The user ID', example: '123e4567-e89b-12d3-a456-426614174000')]
#[PathParameter(name: 'status', type: 'string', description: 'Filter users by status', example: 'active')]
public function show(string $id, string $status)
{
    //...
}

# LoginUserRequest.php
use JkBennemann\LaravelApiDocumentation\Attributes\Parameter;

//..
#[Parameter(name: 'email', ken',         'password' => '

# UserResource.php
use JkBennemann\LaravelApiDocumentation\Attributes\Parameter;

#[Parameter(name: 'id', type: 'string', format: 'uuid', description: 'The user ID', example: '123e4567-e89b-12d3-a456-426614174000')]
#[Parameter(name: 'email', type: 'string', format: 'email', description: 'The users email address')]
#[Parameter(name: 'attributes', type: 'array', description: 'Additional attributes assigned to the user', example: [])]
public function toArray($request): array|JsonSerializable|Arrayable
{
    return [
        'id' => $this->id,
        'email' => $this->email,
        'attributes' => $this->userAttributes ?? [],
    ];
}

# UserController.php

/**
 * Get a list of users
 * 
 * @queryParam per_page integer Number of users per page. Example: 15
 * @queryParam search string Search term for filtering users. Example: john
 * @queryParam status string Filter by user status. Example: active
 */
public function index(Request $request)
{
    //...
}

namespace App\Http\Controllers;

use App\Http\Requests\CreateUserRequest;
use App\Http\Resources\UserResource;
use App\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Resources\Json\ResourceCollection;
use JkBennemann\LaravelApiDocumentation\Attributes\{Tag, Summary, Description, PathParameter, DataResponse};

#[Tag('Users')]
class UserController extends Controller
{
    /**
     * Get a paginated list of users
     * 
     * @queryParam per_page integer Number of users per page. Example: 15
     * @queryParam search string Search term for filtering users. Example: john
     * @queryParam status string Filter by user status. Example: active
     * 
     * @return ResourceCollection<UserResource>
     */
    #[Summary('List all users')]
    #[Description('Retrieves a paginated list of users with optional filtering capabilities')]
    public function index(Request $request): ResourceCollection
    {
        $users = User::query()
            ->when($request->search, fn($q) => $q->where('name', 'like', "%{$request->search}%"))
            ->when($request->status, fn($q) => $q->where('status', $request->status))
            ->paginate($request->per_page ?? 15);

        return UserResource::collection($users);
    }

    /**
     * Get a specific user by ID
     */
    #[PathParameter(name: 'id', type: 'string', format: 'uuid', description: 'The user ID', example: '123e4567-e89b-12d3-a456-426614174000')]
    #[DataResponse(200, description: 'User found successfully', resource: UserResource::class)]
    #[DataResponse(404, description: 'User not found', resource: ['message' => 'string'])]
    public function show(string $id): UserResource|JsonResponse
    {
        $user = User::findOrFail($id);
        return new UserResource($user);
    }

    /**
     * Create a new user
     */
    #[Summary('Create user')]
    #[DataResponse(201, description: 'User created successfully', resource: UserResource::class)]
    #[DataResponse(422, description: 'Validation failed')]
    public function store(CreateUserRequest $request): UserResource
    {
        $user = User::create($request->validated());
        return new UserResource($user);
    }
}

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use JkBennemann\LaravelApiDocumentation\Attributes\Parameter;

class CreateUserRequest extends FormRequest
{
    #[Parameter(name: 'name', eveloper with 5 years experience')]
    #[Parameter(name: 'profile.avatar', type: 'string', format: 'uri', description: 'Avatar image URL')]
    #[Parameter(name: 'preferences.notifications', type: 'boolean', description: 'Enable email notifications', example: true)]
    public function rules(): array
    {
        return [
            'name' => ['

namespace App\Http\Controllers;

use App\Http\Requests\CreatePostRequest;
use App\Http\Resources\PostResource;
use App\Models\Post;
use Illuminate\Http\JsonResponse;
use JkBennemann\LaravelApiDocumentation\Attributes\{Tag, Summary, Description, DataResponse};

#[Tag('Posts')]
#[Summary('Create a new blog post')]
#[Description('Creates a new blog post with the provided content and metadata')]
#[DataResponse(PostResource::class, 201, 'Post created successfully')]
class CreatePostController extends Controller
{
    /**
     * Handle the incoming request to create a new post.
     * 
     * @param CreatePostRequest $request
     * @return JsonResponse
     */
    public function __invoke(CreatePostRequest $request): JsonResponse
    {
        $post = Post::create($request->validated());
        
        return PostResource::make($post)
            ->response()
            ->setStatusCode(201);
    }
}

// Traditional route registration for invokable controllers
Route::post('/posts', CreatePostController::class);

// Mixed with traditional controllers
Route::get('/posts', [PostController::class, 'index']);
Route::post('/posts', CreatePostController::class);  // Invokable
Route::get('/posts/{id}', [PostController::class, 'show']);

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;
use JkBennemann\LaravelApiDocumentation\Attributes\Parameter;

class UserResource extends JsonResource
{
    #[Parameter(name: 'id', type: 'string', format: 'uuid', description: 'Unique user identifier')]
    #[Parameter(name: 'name', type: 'string', description: 'Full name of the user')]
    #[Parameter(name: 'email', type: 'string', format: 'email', description: 'User email address')]
    #[Parameter(name: 'profile', type: 'object', description: 'User profile information')]
    #[Parameter(name: 'created_at', type: 'string', format: 'date-time', description: 'Account creation timestamp')]
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'profile' => [
                'bio' => $this->profile?->bio,
                'avatar' => $this->profile?->avatar,
            ],
            'preferences' => [
                'notifications' => $this->preferences['notifications'] ?? true,
                'theme' => $this->preferences['theme'] ?? 'light',
            ],
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

namespace App\Http\Controllers;

use App\DTOs\UserData;
use App\DTOs\AdminData;

bash
php artisan vendor:publish --tag="api-documentation-config"

bash
php artisan storage:link

json
"scripts": {
    "post-deploy": [
        "@php artisan documentation:generate"
    ]
}

bash
php artisan documentation:generate

bash
php artisan documentation:generate --file=api-v1