Client Api Document Bundle Laravel Package

Getting Started

Before you install anything, confirm the framework target. The -bundle suffix is Symfony's naming convention (*Bundle with a DependencyInjection/Extension class and services.yaml). Laravel has no bundle concept. Read composer.json first:

• If it requires symfony/framework-bundle and symfony/dependency-injection, stop — it will not autoload into a Laravel app without a shim, and the integration cost exceeds reimplementing the idea with Scramble.
• If it only requires PSR interfaces and a router abstraction, it might be portable, but treat that as unverified until you've read the service registration path.

If you are on Symfony (or the package turns out to be framework-agnostic):

1. composer require --dev n1n1du44/client-api-document-bundle — dev-only, always.
2. Register the bundle in config/bundles.php.
3. Confirm zero-config claim by hitting the documented route (typically something like /api/doc). If nothing appears without config, the "zero-config" bullet is aspirational — look at the bundle's Configuration.php for required keys.
4. First use case — the 20-minute spike: generate a spec for three representative endpoints (one with path params, one with a request body, one with a nested resource). Do not try to document your whole API first. The goal is to see whether the output is a valid OpenAPI artifact or a bespoke JSON shape.

Where to look first, in order:

• composer.json — framework target, PHP version, whether it declares an OpenAPI dependency at all.
• DependencyInjection/*Extension.php — what config keys exist, what services get wired, whether anything runs at runtime vs. build time.
• The controller/route introspection class — this is the actual "product." If it's 200 lines of ReflectionClass against controllers, you can read it in an afternoon and it's a reference implementation.
• Any Tests/ directory — the presence or absence of a test that asserts output shape (not just "doesn't throw") is your signal on quality.

Implementation Patterns

Treat it as a build-time generator, never a runtime dependency. The value is a spec artifact produced in CI. Pattern:

composer run-script api-docs      # generate to storage/api/openapi.json
spectral lint storage/api/openapi.json
git diff --exit-code storage/api/openapi.json   # drift gate

If the package serves a UI at request time, mount it behind APP_DEBUG and local network only, or don't mount it — serve the generated spec through a tool you control.

Route introspection pattern (the main workflow). The generator reads your controllers and emits documentation for each public action. Day-to-day this means:

• Add a controller → run the generator → diff the spec → commit the diff as part of the same PR.
• Refactor a route signature → the diff is your review artifact. This is the single best reason to prefer generation over hand-maintained specs: the doc change is reviewed alongside the code change.

Attribute/annotation pattern. Most generators of this shape support adding metadata via PHP attributes (e.g., descriptions, examples, response codes) that route introspection can't infer. Check the source for which attribute classes it defines. If none, you will not be able to document response bodies, auth requirements, or error shapes — which makes the output a route list, not an API contract.

Grouping for multi-API projects. The description advertises grouping. In practice this maps to "tag endpoints by prefix or bundle config." Wire it early if you have /v1 and /v2 or admin vs. public surfaces — retrofitting grouping after 100 endpoints is tedious.

The Laravel-native equivalent, if you're not on Symfony (recommended):

• dedoc/scramble — route-derived OpenAPI, Laravel service provider, actively maintained. Drop-in for the introspection pattern above.
• knuckleswtf/scribe — more opinionated, generates docs and a static HTML UI.
• zircote/swagger-php — attribute-driven, framework-agnostic. Use this when you want the spec to be the source of truth rather than the routes.

Both Scramble and Scribe give you the same generate → lint → diff CI loop without the framework-mismatch tax.

Integration tip for the diff-gate: commit the generated spec to the repo. Yes, "don't commit generated files" is a general rule — this is the exception. The committed artifact is the contract, and the diff in the PR is how reviewers see the contract change. Combine with a --check mode in CI so forgetting to regenerate fails the build.

Gotchas and Tips

Silent drift is the #1 failure mode of every doc generator. A generator that emits plausible-but-wrong OpenAPI is worse than no generator, because downstream consumers (SDK codegen, gateway imports, contract tests) trust the artifact. Mitigations that actually work:

• Spectral lint in CI. Catches structural invalidity and style violations that break codegen.
• Contract tests: run SDK generation or a schema validator against the committed spec on every PR.
• The git diff --exit-code gate. If the spec changed but the PR didn't touch the generator or an endpoint, you have a nondeterministic generator. Fix it before it hides real changes.

Composer graph conflicts. If the package pulls any symfony/* components into a Laravel app, you'll hit illuminate/support vs symfony/console version overlaps during composer update. Symptoms: unresolvable dependency graphs, or a successful install that silently pulls an ancient symfony/polyfill chain. Run composer why symfony/console after install and check whether the lock file moved on packages you didn't intend to touch.

Pin the exact version, not a caret range. With zero dependents and no visible release cadence, a ^1.0 constraint means a rogue patch release ships into your CI silently. "n1n1du44/client-api-document-bundle": "1.2.3" (or a commit hash via a VCS repository entry) is the correct constraint. Review the diff before bumping.

Keep it in require-dev. Even if generation works, nothing in production should autoload a doc generator. If you find yourself needing a --no-dev exclusion in your Dockerfile, you've already lost — audit the install path and confirm the package isn't reachable from the app autoloader in prod.

Config quirks to expect from a small package:

• Configuration.php may declare keys but never read them (dead config). Grep each key in the source; if it isn't used, don't set it — you'll document behavior that doesn't exist.
• Theming advertised in the README often means "one CSS variable exists." Confirm before you plan a custom theme.
• "Zero-config" frequently means "works for the maintainer's app." Budget a half-day for config discovery.

Extension points / fork strategy. If you decide to keep it, fork deliberately:

• Vendor it as a path repository or a git VCS entry pinned to a commit.
• Add a test that snapshots the generated spec for your representative endpoints. This is the regression net you don't inherit.
• Name an owner. "The team" is not an owner. A named engineer with a standing task each framework-upgrade cycle is.
• Read every file that writes to disk or shells out (exec, system, file_put_contents, eval). With no downstream reviewers, you are the only supply-chain check.

The realistic verdict for a Laravel codebase: this package's best use is as a reference implementation. Read its route-to-schema mapping, steal the ideas that are useful, and implement them on Scramble or zircote/swagger-php. That gives you the same CI loop — generate, lint, diff — with a dependency you can actually get support for. The day-to-day developer experience you're buying (docs that don't drift from code) is achievable in Laravel in an afternoon with maintained tooling; the day-to-day you're risking with this package is an unowned dependency sitting on the CI critical path every time you upgrade PHP.