docuccino / laravel

v0.15.0 2026-09-09 16:05 UTC

Requires

• php: ^8.3
• docuccino/attributes: v0.15.0
• docuccino/core: v0.15.0
• illuminate/cache: ^12.0 || ^13.0
• illuminate/console: ^12.0 || ^13.0
• illuminate/contracts: ^12.0 || ^13.0
• illuminate/database: ^12.0 || ^13.0
• illuminate/process: ^12.0 || ^13.0
• illuminate/routing: ^12.0 || ^13.0
• illuminate/support: ^12.0 || ^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• docuccino/inference-phpstan: v0.15.0
• illuminate/testing: ^12.0 || ^13.0
• lorisleiva/laravel-actions: ^2.0
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^4.0
• phpunit/phpunit: ^11.5 || ^12.0
• spatie/laravel-data: ^4.0
• spatie/laravel-json-api-paginate: ^2.0
• timacdonald/json-api: ^1.0@beta

Suggests

• docuccino/inference-phpstan: Required for static type inference — install as a dev dependency: composer require --dev docuccino/inference-phpstan. Without it documentation comes from docblocks and attributes only.
• illuminate/testing: Required by the contract-testing helpers (Docuccino\Laravel\Testing) — every Laravel application already has it through laravel/framework.
• laravel/passport: ^12.0 || ^13.0 — documents the OAuth2 security scheme and the scopes each route's middleware requires.
• laravel/sanctum: ^4.0 — documents the bearer-token security scheme and the abilities each route's middleware requires.
• lorisleiva/laravel-actions: ^2.0 — reads action classes used as controllers: the dispatched method's signature, a body from rules(), a 403 from authorize().
• phpunit/phpunit: Required by the contract-testing helpers (Docuccino\Laravel\Testing), which are only ever loaded from a test suite.
• spatie/laravel-data: ^4.0 — documents Data classes as component schemas and request bodies, including name mapping, wrapping and rules() overrides.
• spatie/laravel-json-api-paginate: ^2.0 — documents the page[number] / page[size] / page[cursor] parameters and the paginator envelope from jsonPaginate().
• spatie/laravel-permission: ^6.0 — publishes the roles and permissions a route's middleware requires (opt-in per document).
• spatie/laravel-query-builder: ^7.0 — documents the filter[…], sort, include and fields[…] parameters from the query's allow-lists.
• timacdonald/json-api: ^1.0@beta — documents JSON:API resources as JSON:API documents, plus their include and fields parameters.

MIT

• Tom Martin

• laravel
• swagger
• openapi
• rest-api
• api-documentation
• openapi-generator
• documentation-generator
• uir
• api-docs
• laravel-openapi
• scramble-alternative

Published on Packagist.org on 2026-09-09 16:05 UTC

README

Automatic OpenAPI documentation for Laravel APIs, generated from the real types in your code.

Docuccino reads your routes, form requests, API resources, Eloquent models and exception handling, and writes an OpenAPI 3.2 or 3.1 document — including the error responses your application actually returns. You get a Swagger-style reference you can serve, host anywhere, or gate your CI on, without hand-writing annotations to get started.

composer require docuccino/laravel
composer require --dev docuccino/inference-phpstan
php artisan docuccino:install

Then open the bundled Scalar viewer at /docs/api.

What you get

• Error responses without configuration — read from your app's real exception handling (render callbacks, render(), Responsable::toResponse()), with the thrown type narrowed so instanceof branches resolve.
• Query Builder parameters, recovered — allowedFilters, allowedSorts and allowedIncludes folded through helper methods several calls deep, with pagination parameters when the call graph reaches a paginating terminal.
• A semantic diff you can gate on — docuccino:diff --enforce compares two documents over stable identities and fails the build when a breaking change ships without the version bump its policy requires.
• Byte-deterministic output — identical code produces identical bytes, so a regenerated document never drifts and a diff only shows what really changed.
• Provenance for every field — docuccino:explain "POST /api/invoices" prints which layer produced each value and what it overrode.

Install

Where your docs need to be readable decides how you install.

Serve docs from your app — the viewer live on a deployed environment:

composer require docuccino/laravel
composer require --dev docuccino/inference-phpstan   # powers type inference

Docs in development only, or a document you host elsewhere (ReadMe, Bump.sh, any OpenAPI host) — keep both dev-only, so composer install --no-dev ships neither:

composer require --dev docuccino/laravel docuccino/inference-phpstan

Analysis is a build-time job either way: the inference engine runs wherever you generate the document, never on a production host. Without the engine, documentation comes from docblocks and attributes only — and every export warns that it did.

Then:

php artisan docuccino:install

It publishes docuccino.yaml and config/docuccino.php (never replacing one you already have), reports how many of your routes the default api/* pattern matches and which prefixes they sit under when none do, says whether the engine is installed, and offers a first export.

Usage

Generate and export the default document:

php artisan docuccino:export

Other commands: docuccino:install, docuccino:diff, docuccino:validate, docuccino:cache, docuccino:clear, and docuccino:explain "POST /api/invoices" — which prints, field by field, which precedence layer produced each value of one endpoint and what it overrode.

Register your own extensions from any service provider:

use Docuccino\Laravel\Facades\Docuccino;

Docuccino::extend(MyOperationExtension::class);

Contract testing

Docuccino\Laravel\Testing\AssertsApiContract holds the requests and responses your test suite already produces to the document Docuccino generates, and a failure names the producer and the file:line the schema came from. It also reports the documented endpoints your suite never exercises, validates every published example against its own schema, and gates breaking changes and a stale committed artifact.

$this->getJson('/api/invoices')->assertValidExchange();

ApiContract::record() turns the same seam into examples: the responses your suite produced are written to committed files, keyed by operation id and with credentials replaced, which the build reads. The document build still runs none of your endpoints — the execution happened in your tests.

Test-only: nothing registers it, and the service provider never touches it. See contract testing.

Part of Docuccino

Package	Role
docuccino/laravel ← you are here	The Laravel adapter: provider, config, commands, viewer, integrations.
docuccino/core	Framework-agnostic document model, canonicalizer, identities, emitters, diff.
docuccino/inference-phpstan	PHPStan + Larastan type inference. Install as a dev dependency.
docuccino/attributes	Dependency-free PHP attribute classes.

Documentation

Full documentation is at docs.docuccino.app:

• Getting started
• Configuration reference
• Commands · Attributes
• Package support
• Writing an integration
• Comparisons: vs Scramble · vs Scribe

Issues and contributing

This repository is a read-only subtree split of docuccino/docuccino. Open issues and pull requests on the monorepo — commits pushed here are overwritten. See CONTRIBUTING.md.

License

MIT. See LICENSE.