Installation

Docuccino generates OpenAPI documentation from the real shape of your Laravel application. It reads your routes, controllers, form requests, resources, models, and exception handling and produces an accurate document — with no annotations to start.

Requirements

PHP 8.3+

Laravel 12 or 13

Install

1. Install the packages. Where do your docs need to be readable? That’s the only question — pick the tab that matches and paste:

   Serve docs from your app

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

   Readers hit /docs/api on a deployed environment. The adapter ships to production and serves a committed artifact or a warmed cache; the engine stays a dev dependency because analysis belongs wherever you generate, and a production host has no business reading your source.

   Docs in development only

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

   You read the docs locally and ship nothing. Everything is dev-only, so composer install --no-dev puts neither package in your production vendor/ — no service provider, no viewer route, no commands. Generate and browse /docs/api on your own machine.

   Host the spec elsewhere

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

   Your docs live on an external host — ReadMe, Bump.sh, Redocly, or anything that takes an OpenAPI file. Export in CI and upload the artifact; your app never serves docs, so both packages stay dev-only. Generating in CI has the job, and docuccino:export --out= puts the file wherever your upload step wants it.

   The engine is the same package either way: it runs PHPStan with Larastan’s model and container knowledge to read the real types in your code — a build-time job, like your test suite.

2. Publish the config file — optional, but you’ll want it soon:

   php artisan vendor:publish --tag=docuccino-config

   This writes config/docuccino.php. The package’s defaults are already active without it, so publish when you want to change something. Out of the box they document every api/* route in your own application, export to docs/openapi.json, and serve an interactive viewer at /docs/api.

   The published file is plain data on purpose — no imports, no class references — so a dev-only install stays safe when production boots with the packages pruned.

3. Export your first document:

   php artisan docuccino:export

   Wrote /home/you/invoices-api/docs/openapi.json (openapi-3.2).

That’s it. Open docs/openapi.json, or visit /docs/api in your browser — the bundled viewer is live in your local environment out of the box, and closed everywhere else until you name a gate. Your first export walks through what Docuccino read and what it produced.

Every scenario installs the engine

Without the engine — or if it can’t boot — inference degrades to off rather than failing the build. Routes, path parameters, validation rules, middleware-driven security, attributes, and docblocks all keep working, but inferred response shapes, detected query parameters, and automatic error responses go quiet. Every export says so: an engine.not-installed warning naming the command that fixes it. That keeps a CI export safe without letting thin output pass unremarked.

What gets added

Artisan commands

docuccino:export, docuccino:validate, docuccino:diff, docuccino:cache, and docuccino:clear. See the commands reference.

A built-in viewer

An interactive Scalar API reference at /docs/api, its spec at /docs/api.json, served from your own app — no external CDN required.

Automatic integrations

Support for form requests, API resources, Eloquent models, enums, Spatie Data, Spatie Query Builder, Sanctum, Passport, and more — each activates only when you use it.

Extension points

Register your own logic from any service provider with Docuccino::extend(). Every official integration is built with the same tools available to you.

Where things live

• Directoryconfig/

  • docuccino.php the single config file — documents, routes, security, viewer
• Directorydocs/

  • openapi.json your exported document (commit this)
• Directorystorage/

  • Directorydocuccino/ engine scratch files and the fragment cache (add to .gitignore)

    • …

Commit the output

Docuccino’s output is deterministic — identical code always produces byte-for-byte identical output, with no timestamps, absolute paths, or shuffling. Commit docs/openapi.json and you get clean, reviewable diffs on every change, plus the ability to gate CI with docuccino:diff.

Turning it off

Set DOCUCCINO_ENABLED=false and Docuccino goes completely dormant: the viewer routes are never registered and the artisan commands refuse to run. It’s the switch to reach for on a production host that has no business generating documentation — and one you never need if you installed everything as a dev dependency, because there’s nothing on that host to turn off.

Your first exportSee what Docuccino read from your code, and what it emitted.

Configuration referenceEvery option in config/docuccino.php, with its default.