Download the PHP package dskripchenko/laravel-api without Composer

# dskripchenko/laravel-api > 🌐 **English** · [Deutsch](docs/de/README.md) · [Русский](docs/ru/README.md) · [中文](docs/zh/README.md) [](https://github.com/dskripchenko/laravel-api/actions/workflows/tests.yml) [](https://packagist.org/packages/dskripchenko/laravel-api) [](https://packagist.org/packages/dskripchenko/laravel-api) [](LICENSE.md) [](https://laravel.com) [](https://www.php.net) 🌐 [Русский](docs/ru/README.md) | [Deutsch](docs/de/README.md) | [中文](docs/zh/README.md) **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](#quick-start) - [Features](#features) - [Installation](#installation) - [Architecture](#architecture) - [API Versioning](#api-versioning) - [Routing & Middleware](#routing--middleware) - [OpenAPI 3.0 Documentation](#openapi-30-documentation) - [CRUD Scaffolding](#crud-scaffolding) - [Testing](#testing) - [Configuration](#configuration) - [Error Handling](#error-handling) - [IDE support](#ide-support) - [Comparison with Alternatives](#comparison-with-alternatives) - [API Reference](#api-reference) - [License](#license) ## Quick Start **Result:** - `GET /api/v1/user/list` — API endpoint - `GET /api/doc` — Auto-generated API documentation (Scalar) ## Features | Feature | Description | |---------|-------------| | **Versioned routing** | `api/{version}/{controller}/{action}` with inheritance between versions | | **OpenAPI 3.0** | Auto-generated from `@input`/`@output` docblocks — no YAML files | | **CRUD scaffolding** | Complete search/create/read/update/delete with filtering, sorting, pagination | | **Middleware cascade** | Global → controller → action with fine-grained exclusion | | **Response templates** | Reusable `$ref` schemas in `components/schemas` | | **Security schemes** | `@security` tag + `securitySchemes` for Bearer/API key auth | | **Nested parameters** | Dot-notation: `@input string $address.city` → nested JSON schema | | **File uploads** | `@input file $avatar` → auto `multipart/form-data` | | **Multiple responses** | `@response 200 {Success}` / `@response 422 {Error}` | | **Header parameters** | `@header string $Authorization` — aggregated from controller + middleware | | **Soft deletes** | Built-in `restore()` and `forceDelete()` in CrudService | | **Request tracing** | `RequestIdMiddleware` — `X-Request-Id` propagation + log context | | **Optional output fields** | `@output string ?$email` — marks response fields as optional in OpenAPI schema | | **TypeScript generation** | `api:generate-types` — generates TS interfaces from OpenAPI spec | | **Named routes** | Each action registered as a named Laravel route — `route('api.v1.user.list')` | | **API export** | `api:export` — Postman Collection, HTTP Client (.http), Markdown, cURL | | **Markup linting** | `api:lint` — catches renamed actions, dangling templates, unknown types | | **IDE support** | [PhpStorm plugin](https://github.com/dskripchenko/laravel-api-idea) — highlighting, inspections, quick fixes, endpoint list | | **Test helpers** | `assertApiSuccess()`, `assertApiError()`, `assertApiValidationError()` | | **Publishable config** | `config/laravel-api.php` — prefix, URI pattern, HTTP methods | ## Installation ### Requirements - PHP 8.2+ - Laravel 11.x — 13.x ### Install ### Publish config ## Architecture ### Request lifecycle ### Response format Every response is wrapped in a standard envelope: ### Directory structure ## API Versioning API versions use **PHP class inheritance** — later versions extend earlier ones: V2 automatically inherits `list`, `show`, `create`, `update` from V1, while overriding the controller and modifying actions. ## Routing & Middleware ### Action configuration ### Middleware cascade 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 ### Nested objects (dot-notation) A list of scalars takes `[]` with no child: `@input string $tags[]`. ### Fields known only at runtime When the fields depend on the route — one generic controller registered under a key per entity — `@input [method]` asks a controller method, and the method is told which operation is being described: The method may return docblock lines (`['string $email Email']`) or a JSON Schema object, which goes into the spec as it is — constraints and all. `@output [method]` works the same way. See [docs/docblock-tags.md](docs/en/docblock-tags.md#dynamic-inputs-from-a-method). ### Headers, security, responses ### Response templates Enable reusable schemas via `components/schemas`: **Shorthand syntax reference:** | Syntax | Meaning | Example | |--------|---------|---------| | `type` | Optional field | `'number'`, `'string'`, `'object'` | | `type!` | Required field | `'integer!'`, `'string!'` | | `type(format)` | With format | `'string(date-time)'`, `'string(email)'` | | `type(format)!` | Format + required | `'string(email)!'` | | `@Model` | `$ref` to schema | `'@Customer'` | | `@Model[]` | Array of `$ref` | `'@OrderItem[]'` | Array format (`['type' => 'string', 'required' => true]`) is also supported and can be mixed with shorthand in the same template. **Response envelope.** Every response really leaves as `{success, payload}` (see [Response format](#response-format)). `public static $responseEnvelope = true;` on the Api class makes the spec say so: templates then describe payloads, and every response — `@output` fields, `{Template}` refs, error codes — is wrapped. Templates may nest (`'client!' => ['email' => 'string(email)']`, `['string']`, `[['id' => 'integer!']]`), and a custom envelope is a field map with `'{payload}'` where the body goes. Details: [docblock-tags.md](docs/en/docblock-tags.md#response-envelope). ### Linking to a single endpoint The reference page addresses every operation by a hash, and `DocLink` builds it without opening a browser — for a ticket, a README, or an IDE: The first segment is the API version, and it is deliberate: the page is handed an explicit slug per version, so a link survives the docblock summary being reworded. An action declaring several HTTP methods is several operations on the page — one anchor each. > Full tag reference: [docs/docblock-tags.md](docs/en/docblock-tags.md) | Linting: [docs/linting.md](docs/en/linting.md) | Cookbook: [docs/cookbook.md](docs/en/cookbook.md) ## CRUD Scaffolding Implement `CrudService` for instant CRUD endpoints: ### Search with filtering, sorting, pagination **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: ## Testing ## TypeScript Generation Generate TypeScript interfaces from your OpenAPI spec: Given `@output integer $id` and `@output string ?$email`, the generator produces: Component schemas, operation inputs, and outputs are all generated. See [docs/cookbook.md](docs/en/cookbook.md#recipe-8-generate-typescript-interfaces) for details. ## IDE support The markup this package reads is not part of any grammar PhpStorm knows, so it shows as one grey blob of prose — and everything the package fails quietly at fails quietly there too. There is a plugin for that: **[dskripchenko/laravel-api-idea](https://github.com/dskripchenko/laravel-api-idea)**. **Installing.** It is distributed from its own repository rather than from JetBrains Marketplace. Add the plugin repository once — Settings | Plugins | ⚙ | *Manage Plugin Repositories…* | **+** — then install *Laravel API* from the Marketplace tab as usual; updates arrive the same way. Paste the address without a trailing space — the IDE encodes it into the URL, and the resulting 404 is reported as *Connection failed*. Or take `laravel-api-idea-.zip` from any [release](https://github.com/dskripchenko/laravel-api-idea/releases) and use *Install Plugin from Disk…*. PhpStorm, or IntelliJ IDEA Ultimate with the PHP plugin. IDEA Community cannot run it — the plugin hangs off the PHP plugin's PSI, and JetBrains does not publish that for Community. **While you type** - Highlights `@input`, `@output`, `@header`, `@response`, `@security`, `@default`, `@example` — types, formats, variables, template references and status codes, so a line the generator has stopped understanding stops looking like the ones it still does. - Reports markup that does not parse, where it is written, instead of letting it vanish from the spec. - Flags unknown types with the consequence named: the generator will call the field `string`. - Compares the markup against `$request->validate([...])`. A validated field the docblock never mentions is reported on the rule itself, with a quick fix that writes the tag from it — `email` becomes `string(email)`, a rule that is not `required` becomes optional, `in:a,b` becomes an enumeration. - Marks a `@response` template or a `@security` scheme nothing declares, and offers to declare the template — creating `getOpenApiTemplates()` when the class has none. - Turns the silent 404 red: an action pointing at a missing, non-public or static method is an error while typing, with a quick fix that writes the method, shaped like the ones already in the class. - Completes types, formats, template names, security schemes and status codes. **Getting around** - Ctrl+Click from `{TemplateName}`, `@Model`, `@security Scheme` and `@input [method]` to their declarations. - Find Usages on a response template — every docblock naming it. A template read only by the generator otherwise looks unused to the IDE. - Gutter arrows both ways between the route map and the controllers. An action with no arrow points at a method that is not there. - A line above the controller method opening this endpoint's own page in `/api/doc` — see [Linking to a single endpoint](#linking-to-a-single-endpoint) for how that address is built. - Every endpoint the route map declares, in one searchable tool window, with the version it answers under. **On demand** - Runs `api:lint` and makes its findings clickable. - Exports the endpoint under the caret as a request — Bruno, cURL, HTTP Client, Postman or Markdown — through `api:export --endpoint`. ## Linting The markup fails quietly: an action whose method was renamed answers 404 — the same 404 as a wrong URL — and a `@response` naming a template that does not exist becomes a `$ref` into nothing, in a spec that still validates. It reads the route map and the docblocks with the same parser the OpenAPI generator uses, and also reports an action that validates its input without declaring any (`input.undeclared`). Full list of rules: [docs/linting.md](docs/en/linting.md). ## API Export Export your API spec in multiple formats: Options: `--api-version=v1` (specific version), `--output=path` (custom file). By default, generates per-version files (`v1.json`, `v1.http`, `v1.md`, `v1.sh`). Bruno is a directory rather than a document — a manifest, an environment and one `.bru` per request — so `--output` names a directory and `--stdout` is refused. The point of it is that a collection can live in the repository next to the code that produces it, and a diff of it reads. ### One endpoint A collection of two hundred requests is not what someone wants who is about to try one: The endpoint is spelled the way the package names its routes — `version.controller.action` — so what is copied out of a log or a route list is what the command takes. `--method=get` picks one when the action answers several. Every format supports this, and none of them has a special case for it: the spec is narrowed to one path first, and each exporter then does exactly what it already did. ## Configuration Publish the configuration file: ## Error Handling ### ApiException ### Custom error handlers 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: ## Comparison with Alternatives ### vs. Classical Laravel approach (manual routes + FormRequest) | Aspect | Classical Laravel | laravel-api | |--------|------------------|-------------| | **Route definition** | `routes/api.php` — one route per endpoint, manual versioning | `getMethods()` — declarative array, versions via class inheritance | | **Versioning** | Manual: route groups, separate controllers, copy-paste | Automatic: `V2 extends V1`, inherit/override/disable actions | | **Documentation** | Separate process: write OpenAPI YAML manually or use annotations | Auto-generated from `@input`/`@output` docblocks | | **Response format** | Ad-hoc per controller, no standard envelope | Standardized `{success, payload}` envelope everywhere | | **CRUD boilerplate** | Write controller + FormRequest + Resource for each entity | Implement `CrudService` (4 methods), get 6+ endpoints | | **Middleware per action** | Route-level middleware or controller middleware groups | Fine-grained: global → controller → action with exclusion | | **Testing** | `$this->getJson('/api/v1/users')` | `$this->api('v1', 'user', 'list')` + assertion helpers | | **Learning curve** | Standard Laravel knowledge | Learn `getMethods()` structure + docblock tags | | **Flexibility** | Full control over everything | Constrained to package conventions | | **When to choose** | Complex APIs with non-standard routing, GraphQL, event-driven APIs | REST APIs with versioning, standard CRUD, auto-documentation needs | **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) | Aspect | L5-Swagger | laravel-api | |--------|-----------|-------------| | **Approach** | OpenAPI-first: write annotations, generate docs | Code-first: write docblocks, docs + routing together | | **Annotation style** | Full OpenAPI annotations (`@OA\Get`, `@OA\Schema`, ...) | Lightweight custom tags (`@input`, `@output`, `@header`) | | **Annotation verbosity** | High: 15-30 lines per endpoint for full spec | Low: 3-10 lines per endpoint | | **Routing** | None — documentation only, routes defined separately | Integrated — routing + docs from single `getMethods()` | | **Versioning** | Manual — separate annotation groups | Built-in — class inheritance | | **CRUD generation** | None | Built-in `CrudService` + `CrudController` | | **Response format** | Any — you define schemas | Fixed `{success, payload}` envelope | | **OpenAPI coverage** | Full OpenAPI 3.0 spec support | Subset: covers 90% of common use cases | | **IDE support** | Plugin support for `@OA\*` annotations | [Plugin](https://github.com/dskripchenko/laravel-api-idea): highlighting, inspections, quick fixes, navigation, endpoint list, `api:lint` runner | | **Ecosystem** | Large community, swagger-php underneath | Smaller, focused package | | **Spec customization** | Full control over every OpenAPI field | Limited to supported tags | | **When to choose** | API-first design, full OpenAPI compliance needed, existing routes | Rapid development, versioned APIs, integrated routing + docs | **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) - Fixed response format - Smaller community and ecosystem - Not suitable for API-first (design-first) workflow ### vs. Scramble (dedoc/scramble) | Aspect | Scramble | laravel-api | |--------|---------|-------------| | **Approach** | Zero-config: infers spec from code (types, FormRequest, routes) | Docblock tags: explicit `@input`/`@output` annotations | | **Route integration** | Uses Laravel's native routes | Custom routing via `getMethods()` | | **Documentation source** | PHP types, FormRequest rules, return types | Docblock annotations | | **Manual annotations** | Optional, for edge cases | Required for all endpoints | | **Versioning** | None built-in | Built-in class inheritance | | **CRUD** | None | Built-in CrudService | | **Setup effort** | Minimal — install and it works | Moderate — define module, API class, provider | | **When to choose** | Standard Laravel routes, minimal documentation effort | Custom routing, versioning, CRUD needs | ### 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 | Class | Methods | |-------|---------| | `ApiController` | `success($payload, $status)`, `error($payload, $status)`, `validationError($messages)`, `created($payload)`, `noContent()`, `notFound($message)` | | `CrudController` | `meta()`, `search(CrudSearchRequest)`, `create(Request)`, `read(Request, int)`, `update(Request, int)`, `delete(int)` | | `ApiDocumentationController` | `index()` | ### Services | Class | Methods | |-------|---------| | `CrudService` | `meta()`, `query()`, `resource()`, `collection()`, `search()`, `create()`, `read()`, `update()`, `delete()`, `restore()`, `forceDelete()` | | `ApiResponseHelper` | `say($data, $status)`, `sayError($data, $status)` | ### Components | Class | Methods | |-------|---------| | `BaseApi` (all methods are `static`) | `getMethods()`, `make()`, `getOpenApiTemplates()`, `getOpenApiSecurityDefinitions()`, `beforeCallAction()`, `afterCallAction()`, `getMiddleware()` | | `BaseModule` | `getApi($version)`, `makeApi()`, `getApiVersionList()`, `getApiPrefix()`, `getApiUriPattern()`, `getAvailableApiMethods()`, `getDocMiddleware()` | | `Meta` | `string($key, $name)`, `integer($key, $name)`, `number($key, $name)`, `boolean($key, $name)`, `hidden($key, $name)`, `select($key, $name, $items)`, `file($key, $name, $src)`, `action($key, $condition)`, `crud()`, `getOpenApiInputs()`, `getColumnKeys()` | ### Middleware | Class | Purpose | |-------|---------| | `ApiMiddleware` | Abstract base — catches `ApiException` and generic exceptions | | `RequestIdMiddleware` | Generates/propagates `X-Request-Id`, adds to `Log::shareContext()` | ### Exceptions | Class | Purpose | |-------|---------| | `ApiException` | Exception with `errorKey` string for structured error responses | | `ApiErrorHandler` | Registry of exception handlers by class, with parent class traversal | ### Facades | Facade | Resolves to | |--------|------------| | `ApiRequest` | `BaseApiRequest` — version, controller, action, HTTP method | | `ApiModule` | `BaseModule` — version resolution, route configuration | | `ApiErrorHandler` | `ApiErrorHandler` — exception handler registry | ## License MIT License. See [LICENSE.md](LICENSE.md) for details.