dskripchenko/laravel-api

🌐 Русский | Deutsch | 中文

A Laravel package for versioned API routing, OpenAPI 3.0 auto-documentation, and CRUD scaffolding.

Build versioned APIs with automatic OpenAPI documentation generated from PHP docblocks — no YAML/JSON schemas to maintain, no annotation libraries to learn.

Table of Contents

• Quick Start
• Features
• Installation
• Architecture
• API Versioning
• Routing & Middleware
• OpenAPI 3.0 Documentation
• CRUD Scaffolding
• Testing
• Configuration
• Error Handling
• Comparison with Alternatives
• API Reference
• License

Quick Start

composer require dskripchenko/laravel-api

// 1. Define your API class
class Api extends \Dskripchenko\LaravelApi\Components\BaseApi
{
    public static function getMethods(): array
    {
        return [
            'controllers' => [
                'user' => [
                    'controller' => UserController::class,
                    'actions' => ['list', 'show', 'create'],
                ],
            ],
        ];
    }
}

// 2. Define your module
class ApiModule extends \Dskripchenko\LaravelApi\Components\BaseModule
{
    public function getApiVersionList(): array
    {
        return ['v1' => Api::class];
    }
}

// 3. Define your ServiceProvider
class ApiServiceProvider extends \Dskripchenko\LaravelApi\Providers\ApiServiceProvider
{
    protected function getApiModule() { return new ApiModule(); }
}

// 4. Write a controller with docblocks
class UserController extends \Dskripchenko\LaravelApi\Controllers\ApiController
{
    /**
     * List users
     * @input integer ?$page Page number
     * @output integer $id User ID
     * @output string $name User name
     */
    public function list(Request $request): JsonResponse
    {
        return $this->success(User::paginate()->toArray());
    }
}

Result:

• GET /api/v1/user/list — API endpoint
• GET /api/doc — Auto-generated API documentation (Scalar)

Features

Installation

Requirements

• PHP 8.1+
• Laravel 6.x — 12.x

Install

composer require dskripchenko/laravel-api

Publish config

php artisan vendor:publish --tag=laravel-api-config

Architecture

Request lifecycle

HTTP Request
  └─ ApiServiceProvider (registers route: api/{version}/{controller}/{action})
      └─ BaseApiRequest (parses version, controller, action from URI)
          └─ BaseModule::getApi() (version string → BaseApi subclass)
              └─ BaseApi::make()
                  ├─ getMethods() → resolve controller + action
                  ├─ Middleware cascade (global → controller → action)
                  └─ app()->call(Controller@action)
                      └─ JsonResponse {success: true, payload: {...}}

Response format

Every response is wrapped in a standard envelope:

// Success
{"success": true, "payload": {"id": 1, "name": "John"}}

// Error
{"success": false, "payload": {"errorKey": "not_found", "message": "User not found"}}

// Validation error
{"success": false, "payload": {"errorKey": "validation", "messages": {"email": ["Required"]}}}

Directory structure

src/
├── Components/        BaseApi, BaseModule, Meta
├── Console/Commands/  ApiInstall, BaseCommand
├── Controllers/       ApiController, CrudController, ApiDocumentationController
├── Exceptions/        ApiException, ApiErrorHandler, Handler
├── Facades/        ApiRequest, ApiModule, ApiErrorHandler
├── Interfaces/     CrudServiceInterface, ApiInterface
├── Middlewares/    ApiMiddleware, RequestIdMiddleware
├── Providers/      ApiServiceProvider, BaseServiceProvider
├── Requests/       BaseApiRequest, CrudSearchRequest
├── Resources/      BaseJsonResource, BaseJsonResourceCollection
├── Services/       ApiResponseHelper, CrudService
└── Traits/
    ├── OpenApiTrait
    └── Testing/       MakesHttpApiRequests

API Versioning

API versions use PHP class inheritance — later versions extend earlier ones:

// V1: full API
class ApiV1 extends BaseApi {
    public static function getMethods(): array {
        return ['controllers' => [
            'user' => [
                'controller' => UserControllerV1::class,
                'actions' => ['list', 'show', 'create', 'update', 'delete'],
            ],
        ]];
    }
}

// V2: inherits V1, modifies selectively
class ApiV2 extends ApiV1 {
    public static function getMethods(): array {
        return ['controllers' => [
            'user' => [
                'controller' => UserControllerV2::class,  // upgraded controller
                'actions' => [
                    'delete' => false,                     // removed in v2
                    'archive',                             // new in v2
                ],
            ],
        ]];
    }
}

V2 automatically inherits list, show, create, update from V1, while overriding the controller and modifying actions.

Routing & Middleware

Action configuration

'actions' => [
    'list',                              // simple: method name = action key
    'show' => 'getById',                 // alias: show → calls getById()
    'disabled' => false,                 // disabled action (404)
    'create' => [
        'action' => 'store',             // explicit method name
        'method' => ['post'],            // allowed HTTP methods (default: ['post'])
        'middleware' => [RateLimit::class],
        'exclude-middleware' => [LogMiddleware::class],
        'exclude-all-middleware' => false,
    ],
]

Middleware cascade

Global middleware (getMethods root)
  └─ Controller middleware
      └─ Action middleware

Each level can exclude middleware from parent levels using exclude-middleware (specific) or exclude-all-middleware (all).

OpenAPI 3.0 Documentation

Documentation is generated automatically from PHP docblocks. No YAML or JSON files to maintain.

Basic tags

/**
 * Create an order
 * Detailed description of the endpoint.
 *
 * @input string $title Order title
 * @input string ?$notes Optional notes
 * @input integer(int64) $amount Amount in cents
 * @input string $status Status [draft,pending,confirmed]
 * @input file ?$attachment Optional file
 *
 * @output integer $id Created order ID
 * @output string(date-time) $createdAt Timestamp
 */

Nested objects (dot-notation)

/** @input object $address Address
 *  @input string $address.city City
 *  @input string $address.zip ZIP code
 *  @input array $items Order items
 *  @input integer $items[].productId Product
 *  @input integer $items[].quantity Quantity */

Headers, security, responses

/**
 * @header string $Authorization Bearer token
 * @header string ?$X-Request-Id Trace ID
 * @security BearerAuth
 * @response 200 {OrderResponse}
 * @response 422 {ValidationError}
 * @deprecated Use createV2 instead
 */

Response templates

Enable reusable schemas via components/schemas:

class Api extends BaseApi {
    public static bool $useResponseTemplates = true;

    public static function getOpenApiTemplates(): array {
        return [
            'OrderResponse' => [
                'id'         => 'integer!',            // required integer
                'title'      => 'string!',             // required string
                'total'      => 'number',              // optional number
                'created_at' => 'string(date-time)',   // with format
                'email'      => 'string(email)!',      // format + required
                'customer'   => '@Customer',           // $ref to another schema
                'items'      => '@OrderItem[]',        // array of $ref
            ],
            'Customer' => [
                'id'   => 'integer!',
                'name' => 'string!',
            ],
            'OrderItem' => [
                'product_id' => 'integer!',
                'quantity'   => 'integer',
                'price'      => 'number',
            ],
        ];
    }

    public static function getOpenApiSecurityDefinitions(): array {
        return [
            'BearerAuth' => ['type' => 'apiKey', 'name' => 'Authorization', 'in' => 'header'],
        ];
    }
}

Shorthand syntax reference:

Array format (['type' => 'string', 'required' => true]) is also supported and can be mixed with shorthand in the same template.

Full tag reference: docs/docblock-tags.md | Cookbook: docs/cookbook.md

CRUD Scaffolding

Implement CrudService for instant CRUD endpoints:

class ProductService extends CrudService {
    public function meta(): Meta {
        return (new Meta())
            ->string('name', 'Name')
            ->number('price', 'Price')
            ->select('status', 'Status', ['active', 'draft'])
            ->crud();
    }
    public function query(): Builder { return Product::query(); }
    public function resource(Model $model): BaseJsonResource { return new BaseJsonResource($model); }
    public function collection(Collection $c): BaseJsonResourceCollection { return BaseJsonResource::collection($c); }
}

Search with filtering, sorting, pagination

POST /api/v1/product/search
{
  "filter": [
    {"column": "status", "operator": "=", "value": "active"},
    {"column": "price", "operator": "between", "value": [10, 100]},
    {"column": "name", "operator": "like", "value": "phone"},
    {"column": "description", "operator": "is_not_null"}
  ],
  "order": [{"column": "price", "value": "desc"}],
  "page": 1,
  "perPage": 20
}

Available operators: =, !=, >, <, >=, <=, in, not_in, like, between, is_null, is_not_null

Security: LIKE values are auto-escaped (%, _, \). All write operations are wrapped in DB::transaction(). Filter array is limited to 50 items.

Soft delete support

CrudService includes restore($id) and forceDelete($id) for models using SoftDeletes. These methods are not exposed via CrudController by default — add custom actions in your controller:

'restore' => ['action' => 'restore', 'method' => ['post']],
'forceDelete' => ['action' => 'forceDelete', 'method' => ['post']],

Testing

use Dskripchenko\LaravelApi\Traits\Testing\MakesHttpApiRequests;

class ProductTest extends TestCase
{
    use MakesHttpApiRequests;

    public function test_list(): void
    {
        $response = $this->api('v1', 'product', 'search');
        $this->assertApiSuccess($response);
    }

    public function test_not_found(): void
    {
        $response = $this->api('v1', 'product', 'read', ['id' => 999]);
        $this->assertApiError($response, 'not_found');
    }

    public function test_validation(): void
    {
        $response = $this->api('v1', 'product', 'create', []);
        $this->assertApiValidationError($response, ['name']);
    }
}

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=laravel-api-config

// config/laravel-api.php
return [
    'prefix' => 'api',                                          // URL prefix
    'uri_pattern' => '{version}/{controller}/{action}',          // Route pattern
    'available_methods' => ['get', 'post', 'put', 'patch', 'delete'],
    'openapi_path' => 'public/openapi',                           // OpenAPI JSON output
    'doc_middleware' => [],                                       // Middleware for /api/doc
];

Error Handling

ApiException

throw new ApiException('payment_failed', 'Insufficient funds');
// → {"success": false, "payload": {"errorKey": "payment_failed", "message": "Insufficient funds"}}

Custom error handlers

use Dskripchenko\LaravelApi\Facades\ApiErrorHandler;
use Dskripchenko\LaravelApi\Services\ApiResponseHelper;
use Illuminate\Database\Eloquent\ModelNotFoundException;

ApiErrorHandler::addErrorHandler(
    ModelNotFoundException::class,
    fn($e) => ApiResponseHelper::sayError(['errorKey' => 'not_found', 'message' => 'Not found'], 404)
);

Handlers support inheritance: registering a handler for Exception will also catch RuntimeException via class_parents() traversal.

RequestIdMiddleware

Add to your middleware stack for request tracing:

// Reads X-Request-Id from request header or generates UUID
// Adds request_id to Log::shareContext()
// Sets X-Request-Id on response header
Dskripchenko\LaravelApi\Middlewares\RequestIdMiddleware::class

Comparison with Alternatives

vs. Classical Laravel approach (manual routes + FormRequest)

Advantages of laravel-api:

• Zero-maintenance documentation — docblocks are the single source of truth
• Version inheritance eliminates code duplication between API versions
• Standardized response format across all endpoints
• CRUD scaffolding reduces boilerplate by 60-80%

Disadvantages of laravel-api:

• Fixed URI pattern (api/{version}/{controller}/{action}) — not RESTful resource routes
• Opinionated response format — can't easily switch to JSON:API or HAL
• No native support for resource-style URLs (/users/{id} vs /user/show?id=1)

vs. L5-Swagger (DarkaOnLine/L5-Swagger)

Advantages over L5-Swagger:

• 3-5x less annotation code per endpoint
• Routing and documentation are always in sync (single source)
• Built-in API versioning with inheritance
• CRUD scaffolding included
• No need to learn the full OpenAPI annotation specification

Disadvantages compared to L5-Swagger:

• Less OpenAPI coverage (no callbacks, webhooks, links, discriminator)
• No IDE plugin for custom tags
• Fixed response format
• Smaller community and ecosystem
• Not suitable for API-first (design-first) workflow

vs. Scramble (dedoc/scramble)

Summary: When to use laravel-api

✅ Choose laravel-api when:

• You need versioned APIs with inheritance between versions
• You want integrated routing + documentation from a single source
• You need CRUD scaffolding with filtering, sorting, pagination
• You prefer lightweight docblock tags over verbose annotations
• You want a standardized response format across all endpoints

❌ Choose alternatives when:

• You need RESTful resource-style URLs (/users/{id})
• You need full OpenAPI 3.0 compliance (callbacks, webhooks, discriminator)
• You follow API-first (design-first) methodology
• You need GraphQL or non-REST APIs
• You want zero-annotation documentation (→ Scramble)

API Reference

Controllers

Services

Components

Middleware

Exceptions

Facades

License

MIT License. See LICENSE.md for details.